WORLD INTELLECTUAL PROPERTY ORGANIZATION 
International Bureau 




PCT 

INTERNATIONAL APPLICATION PUBLISHED UNDER THE PATENT COOPERATION TREATY (PCT) 



(51) Internationa] Patent Classification 6 ; 
G06F 9/46 



AJ 



(11) International Publication Number: WO 99/49394 

(43) International Publication Date: 30 September 1999 (30.09.99) 



(21) International Application Number: PCT/US99/06223 

(22) International Filing Date: 22 March 1999 (22.03.99) 



(30) Priority Data: 
60/078,946 



23 March 1998 (23.03.98) 



US 



(71) Applicant: MICROSOFT CORPORATION fUS/USJ; One 
Microsoft Way. Redmond, WA 98052 (US). 

(71)(72) Applicants and Inventors: GAGNE, Rejean [CA/CA]; 
4739 Rue Fabre, Montreal, Quebec H2J 3V7 (CA). CAJO- 
LET, Claude [CA/CA]; 535 Avenue Outremont, Outremont, 
Quebec (CA). 

(74) Agent: V1KSN1NS, Ann, S.; Schwegman, Lundberg, Woessner 
& Kluth, P.O. Box 2938, Minneapolis, MN 55402 (US). 



(81) Designated States: AE, AL, AM, AT, AU, AZ, BA, BB, BG, 
BR, BY, CA, CH, CN, CU. CZ, DE, DK, EE, ES, FI, GB, 
GD, GE, GH, GM, HR, HU, ID, IL, IN, IS, JP, KE, KG, 
KP, KR, KZ, LC, LK, LR, LS, LT, LU,!LV, MD, MG, MK, 
MN, MW, MX, NO, NZ, PL, PT, RO, RU, SD, SE, SG, SJ, 
SK, SL, TJ, TM, TR, TT, UA, UG, UZi VN f YU, ZA, ZW, 
AR1PO patent (GH, GM, KE, LS, MW, SD, SL, SZ, UG, 
ZW), Eurasian patent (AM, AZ, BY, KG, KZ, MD, RU, TJ, 
TM), European patent (AT, BE, CH, CY, DE, DK, ES, FI, 
FR, GB, GR, IE, IT, LU, MC, NL, PT, SE), OAPI patent 
(BF, BJ, CF, CG, CI, CM, GA, GN, GW, ML, MR, NE, 
SN, TD, TG). 



Published 

With international search report 

Before the expiration of the time limit for amending the 
claims and to be republished in the event of the receipt of 
amendments. 



(54) Tide: APPLICATION PROGRAM INTERFACES IK AN OPERATING SYSTEM 



226- 



WINDOWS CE APPLICATIONS 



200. 



224 

\ 



222 



| ADD-ON TECHNOLOGIES! | WINDOWS CE SHELL 



OEWK 



220 




218 

\ 


216 


CORE SYSTEM 
INTERFACE 




FILE 
SYSTEM 




COiAJUNGATONS 


214 

i 




212 
\ 


210 


KERNEL 




GWES 




DEVICE 
MANAGER 










OAL 




BUILT-IN 
DRIVERS 




INSTALLABLE 
DRIVERS 


208 


202 
i 


206 


204 


| OEM HARDWARE | 



(57) Abstract 
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APPLICATION PROGRAM INTERFACES IN AN OPERATING SYSTEM 

5 FIELD OF THE INVENTION 

This invention relates generally to computer operating systems, and more 
particularly to application program interfaces for resource limited operating 
systems. 

RELATED FILES 

This application claims the benefit of U.S. Provisional Application No. 
60/078946, filed March 23, 1998, which is hereby incorporated herein by 
reference. 

COPYRIGHT NOTICE/PERMISSION 

A portion of the disclosure of this patent document contains material 
which is subject to copyright protection. The copyiigh! owo-sr Ijg.v wo objection 
to the facsimile reproduction by anyone of the patent document or the patent 
disclosure as it appears in the Patent and Trademark Office patent file or records, 
but otherwise reserves all copyright rights whatsoever. The following notice 
applies to the software and data as described below and in the drawing hereto: 
Copyright © 1998, 1999, Microsoft Coiporation, All Rights Reserved. 

BACKGROUND OF THE INVENTION 
The rapid evolution of personal computer technology continues to 
produce personal computers (PCs) that are smaller, cheaper and faster than their 
predecessors. Where computers once occupied entire rooms, they are now small 
enough to fit in the palm of a user's hand, hence the name "Palm-size PCs". In 
addition, PCs are now small enough to be placed in environments outside of the 
home or office, such as an automobile. Further more, the new PCs may be 
embedded in a variety of consumer devices and specialized industrial controllers. 
For the purposes of this application, all of the above-referenced PCs will be 
referred to collectively as "embedded systems." 
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The reduced size of embedded systems means that certain sacrifices need 
to be made. For example, a typical embedded system does not have fixed or 
removable disk drives such as hard disk, floppy disk, CD-ROM or DVD-ROM 
drives, with the persistent storage of a typical embedded system comprising flash 
5 memory or volatile memory with a battery refresh. In addition, the amount of 
RAM in the typical embedded system is also limited. 

In addition, output resources typical to a desktop PC may be missing or 
severely limited in an embedded system. For example, the display for a typical 
embedded system may comprise a small LCD screen with limited resolution and 
1 0 capable of displaying only grayscale or a limited number of colors. In certain 
environments, such as the automobile, the display may be an LCD screen with a 
limited number of fixed icons and text areas. The display may be augmented 
with a computerized speech facility. 

Similarly, input resources may be limited or adapted for use in embedded 
15 systems. For example, many embedded sy&iems do nci have \i mouse or other 
pointing device. In addition, some hand-held devices do not have a physical 
keyboard. Such embedded devices may use a touch sensitive display in 
conjunction with a virtual keyboard placed on the display. In addition, embedded 
devices may employ speech recognition for input. 
20 As a result of the above, specialized operating systems capable of 

running in the resource-limited environment of the embedded system have been 
developed. An example of such an operating system is the Windows CE™ 
operating system from Microsoft Corporation. 

Applications running on the embedded system must also be capable of 
25 running in the resource limited environment described above. In embedded 
systems comprising Palm-size PCs, these applications are typically specialized 
versions of applications available on the bigger siblings of the Palm-size PC, 
such as calendar programs, personal information managers, calculators, 
dictionaries and the like. 
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In other environments, the applications running on the embedded system 
may be more specialized. For example, in an AutoPC, the applications may 
comprise applications that interface with an audio system, applications that 
report and use position and navigation information, and applications that monitor 
5 the condition and state of various other systems present in the automobile. 

In order to accommodate a large number of different application needs, 
operating systems typically provide APIs (Application Programming Interfaces) 
to a wide variety of functionality that is common to many differing applications. 
Any one application generally uses only a small subset of the available APIs. 
1 0 Providing a wide variety of APIs frees application developers from having to 
write code that would have to be potentially duplicated in each application. 
However, in the resource limited environment of the embedded system, there is 
typically a much more limited set of APIs available. This is because there is 
generally insufficient persistent and non-persistent memory available to support 
15 h large numbly of different APIs. Thus^a developer writing an application for an 
embedded system may find that he or she must develop code that would 
ordinarily be provided by the operating system in a desktop's or other larger 
computer's operating system. 

As a result of the above, there is a need in the art for an operating system 
20 capable of running in the resource limited environment of an embedded system. 
Such an operating system should be customizable and adaptable to the wide 
variety environments that system designers may choose to place embedded 
systems, allowing developers to include only those components and modules that 
are necessary for a particular environment. In addition, the operating system 
25 should include APIs to operating system provided components in order prevent 
applications designers from having to duplicate commonly needed code. Finally, 
the operating system should provide APIs for components and modules that meet 
the unique input and output needs of an embedded system. 
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SUMMARY OF THE INVENTION 

The above-mentioned shortcomings, disadvantages and problems are 
addressed by the present invention, which wi]j be understood by reading and 
studying the following specification. 

A system is presented that includes a set of Application Program 
Interfaces (APIs) for a number of software modules and components for resource 
limited environments. One example of a resource limited environment is the 
embedded system, which comprises a variety of consumer devices and 
specialized industrial controllers, along with hand-held, or palm-size personal 
computers. 

One aspect of the system is that the combination of components and 
modules included in an operating system for resource limited environments is 
customizable and flexible. This allows an embedded system designer to include 
only those components and modules that are necessary for a particular 
environment. As a result, scarce memory is not consumed by unneeded 
components, allowing more memory to be devoted to applications and ofner 
modules and components that are needed in the embedded system. 

Another aspect of the system is that APIs are provided that meet the 
unique input and output needs of the typical embedded system. For example, 
many embedded systems do not provided a keyboard or mouse for input. The 
system provides APIs to components and modules that provide alternative 
mechanisms of providing input. These alternative mechanisms include APIs to 
handwriting recognition engines that "read" strokes on a touch sensitive screen, 
and APIs to voice input components that allow a user to issue spoken commands 
to the system. Further, the system provides APIs to components that output 
audible speech for those environments where a display monitor is impractical. 
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Another aspect of the system is that the handling of "out of memory" 
conditions is customizable by an embedded system designer. This is important 
to systems with limited resources, because out of memory conditions are more 
likely to occur. 

A further aspect of the system is that an API to a position and navigation 
component is provided. This is useful for embedded system environments that 
are mobile, such as automobiles, trucks, and boats. 

The APIs summarized above, and various other APIs, will be described 
in detail in the sections that follow. 

The present invention describes systems, clients, servers, methods, and 
computer-readable media of varying scope. In addition to the aspects and 
advantages of the present invention described in this summary, further aspects 
and advantages of the invention will become apparent by reference to the 
drawings and by reading the detailed description that follows. .... _ 
BRIEF DESCRIPTION OF THE DRA WINGS 
FIG. 3 shows a diagram of the hardware and operoting environmrorin 
conjunction with which embodiments of the invention may be practiced; 

FIG. 2 is a diagram illustrating a system-level overview of exemplary 
embodiments of an operating system for a resource limited environment; and 

FIG. 3 is a diagram further illustrating the relationship of modules, 
components and APIs according to an embodiment of the invention. 

DETAILED DESCRIPTION OF THE INVENTION 
In the following detailed description of exemplary embodiments of the 
invention, reference is made to the accompanying drawings that form a part 
hereof, and in which is shown by way of illustration specific exemplary 
embodiments in which the invention may be practiced. These embodiments are 
described in sufficient detail to enable those skilled in the art to practice the 
invention, and it is to be understood that other embodiments may be utilized and 
that logical, mechanical, electrical and other changes may be made without 
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departing from the spirit or scope of the present invention. The following 
detailed description is, therefore, not to be taken in a limiting sense, and the 
scope of the present invention is defined only by the appended claims. 

The detailed description is divided into four sections. In the first section, 
the hardware and the operating environment in conjunction with which 
embodiments of the invention may be practiced are described. In the second 
section, a system level overview of the invention is presented. In the third 
section, various APIs are presented allowing applications to interface with 
various modules and components of an operating system. Finally, in the fourth 
section, a conclusion of the detailed description is provided. 

Hardware and Operating Environment 
FIG. 1 is a diagram of the hardware and operating environment in 
conjunction with which embodiments of the invention may be practiced. The 
description of FIG. 1 is intended to provide a brief, general description of 
suitable computer hardware and a suitable compe ting environment in 
conjunction with which the invention may be implemented. Although not 
required, the invention is described in the general context of computer- 
executable instructions, such as program modules, being executed by a 
computer, such as a personal computer, a hand-held or palm-size computer, or an 
embedded system such as a computer in a consumer device or specialized 
industrial controller. Generally, program modules include routines, programs, 
objects, components, data structures, etc., that perform particular tasks or 
implement particular abstract data types. 

Moreover, those skilled in the art will appreciate that the invention may 
be practiced with other computer system configurations, including hand-held 
devices, multiprocessor systems, microprocessor-based or programmable 
consumer electronics, network PCS, minicomputers, mainframe computers, and 
the like. The invention may also be practiced in distributed computing 
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environments where tasks are performed by remote processing devices that are 
linked through a communications network. In a distributed computing 
environment, program modules may be located in both local and remote memory 
storage devices. 

5 The exemplary hardware and operating environment of FIG. 1 for 

implementing the invention includes a general purpose computing device in the 
form of a computer 20, including a processing unit 21, a system memory 22, and 
a system bus 23 that operatively couples various system components including 
the system memory to the processing unit 21 . There may be only one or there 
1 0 may be more than one processing unit 2 1 , such that the processor of computer 20 
comprises a single central-processing unit (CPU), or a plurality of processing 
units, commonly referred to as a parallel processing environment. The computer 
20 may be a conventional computer, a distributed computer, or any other type of 
computer; the invention is not so limited. 
1 5 The system bus 23 may be any of several types of bus structures 

including a memory bus or memory controller, a peripheral bus, and a local bus 
using any of a variety of bus architectures. The system memory may also be 
referred to as simply the memory, and includes read only memory (ROM) 24 and 
random access memory (RAM) 25. A basic input/output system (BIOS) 26, 
20 containing the basic routines that help to transfer information between elements 
within the computer 20, such as during start-up, is stored in ROM 24. In one 
embodiment of the invention, the computer 20 further includes a hard disk drive 

27 for reading from and writing to a hard disk, not shown, a magnetic disk drive 

28 for reading from or writing to a removable magnetic disk 29, and an optical 
25 disk drive 30 for reading from or writing to a removable optical disk 31 such as a 

CD ROM or other optical media. In alternative embodiments of the invention, 
the functionality provided by the hard disk drive 27, magnetic disk 29 and 
optical disk drive 30 is emulated using volatile or non-volatile RAM in order to 
conserve power and reduce the size of the system. In these alternative 
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embodiments, the RAM may be fixed in the computer system, or it may be a 
removable RAM device, such as a Compact Flash memory card. 

In an embodiment of the invention, the hard disk drive 27, magnetic disk 
drive 28, and optica] disk drive 30 are connected to the system bus 23 by a hard 
disk drive interface 32, a magnetic disk drive interface 33, and an optical disk 
drive interface 34, respectively. The drives and their associated computer- 
readable media provide nonvolatile storage of computer-readable instructions, 
data structures, program modules and other data for the computer 20. It should 
be appreciated by those skilled in the art that any type of computer-readable 
media which can store data that is accessible by a computer, such as magnetic 
cassettes, flash memory cards, digital video disks, Bernoulli cartridges, random 
access memories (RAMs), read only memories (ROMs), and the like, may be 
used in the exemplary operating environment. 

A number of program modules may be stored on the hard disk, magnetic 
disk 29, optical disk-31, R6M 24, or RAM 25, including au operating system 35., 
one or more application programs 36, other program modules 37, and program ' 
data 38. A user may enter commands and information into the personal 
computer 20 through input devices such as a keyboard 40 and pointing device 
42. Other input devices (not shown) may include a microphone, joystick, game 
pad, satellite dish, scanner, touch sensitive pad, or the like. These and other 
input devices are often connected to the processing unit 21 through a serial port 
interface 46 that is coupled to the system bus, but may be connected by other 
interfaces, such as a parallel port, game port, or a universal serial bus (USB). In 
addition, input to the system may be provided by a microphone to receive audio 
input. 

A monitor 47 or other type of display device is also connected to the 
system bus 23 via an interface, such as a video adapter 48. In one embodiment 
of the invention, the monitor comprises a Liquid Crystal Display (LCD). In 
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addition to the monitor, computers typically include other peripheral output 
devices (not shown), such as speakers and printers. 

The computer 20 may operate in a networked environment using logical 
connections to one or more remote computers, such as a remote computer 49. 
These logical connections are achieved by a communication device coupled to or 
a part of the computer 20; the invention is not limited to a particular type of 
communications device. The remote computer 49 may be another computer, a 
server, a router, a network PC, a client, a peer device or other common network 
node, and typically includes many or all of the elements described above relative 
to the computer 20, although only a memory storage device 50 has been 
illustrated in FIG. 1. The logical connections depicted in FIG. 1 include a local- 
area network (LAN) 51 and a wide-area network (WAN) 52. Such networking 
environments are commonplace in offices, enterprise-wide computer networks, 
intranets and the Internet. 

When used in a LAN-network;;^ e^onmen:, ^/iTiputer 20 is """ 
connected to the local network 51 through a network interface or adapter 53, 
which is one type of communications device. When used in a WAN-networking 
environment, the computer 20 typically includes a modem 54, a type of 
communications device, or any other type of communications device for 
establishing communications over the wide area network 52, such as the Internet. 
The modem 54, which may be internal or external, is connected to the system 
bus 23 via the serial port interface 46. In a networked environment, program 
modules depicted relative to the personal computer 20, or portions thereof, may 
be stored in the remote memory storage device. It is appreciated that the 
network connections shown are exemplary and other means of and 
communications devices for establishing a communications link between the 
computers may be used. 

The hardware and operating environment in conjunction with which 
embodiments of the invention may be practiced has been described. The 
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computer in conjunction with which embodiments of the invention may be 
practiced may be a conventional computer an hand-held or palm-size computer, 
a computer in an embedded system, a distributed computer, or any other type of 
computer; the invention is not so limited. Such a computer typically includes 
one or more processing units as its processor, and a computer-readable medium 
such as a memory. The computer may also include a communications device 
such as a network adapter or a modem, so that it is able to communicatively 
couple other computers. 

System Level Overview 
A system level overview of the operation of an exemplary embodiment 
of the invention is described by reference to FIGs. 2 and 3. The concepts of the 
invention are described as operating in a multiprocessing, multithreaded 
operating environment on a computer, such as computer 20 in FIG. 1 . The 
exemplary operating environment comprises what is known in the art as an 
operating system. Jn this environment one or more app'Mcatiuis, such 
application 226, interface with various modules and components of the operating 
system. In addition, the various modules and components of the operating 
system interface with each other. Finally, the modules, components and 
applications interface with hardware 202 present on the computer through what 
is known in the art as a device driver module, and through an Original 
Equipment Manufacturer (OEM) adaptation layer 208. In one embodiment of 
the invention, there are two types of device drivers, built-in drivers 206 and 
installable drivers 204. The various modules will now be described in further 
detail. 

The core system interface 220 is the module through which applications 
can access the operating system. The core system interface 220 includes 
functions to transfer API calls to the appropriate operating system server process. 

In addition to including or exporting the APIs selected, the core system 
interface 220 includes components to support the following: 
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• Localization 

• Local heap and memory allocation 

• Serial port device driver thunks 

• Telephony API (TAPI) 

5 The shell module 222 manages the user interface and handles such tasks 

as launching software applications. In one embodiment of the invention, the 
operating system provides shell components that enable an embedded system 
designer to develop a customized shell 222 that satisfies the requirements of the 
target platform. Included in these components are: 

10 

• A Control Panel with applets familiar to desktop Windows 
users. The following applets are included: Communications; 
Display; Keyboard; Network; Owner; Password; Power; 
Regional Settings, Remove Programs; Pointing Device 
Settings (Stylus); Sounds and Volume. 

. A Notification API that lets an - application register its- nsnsr 

and an event with the system. When the event occurs, the 
kernel will automatically start the named application. The 
API also allows an application to register a specific date and 
time at which the application should start. 

• Common controls and common dialogs, which are 
designed to provide to the user clear, simple, and 
meaningful information and a means to furnish input to the 
system and applications as needed. 

• A command line processor (that is, a console application) 
that supports a set of standard input and output API calls. 

• Connectivity components (for example, to support remote 
application programming calls) between the development 
workstation and the embedded system target platform. 

In conjunction with a desktop, the shell module 222 also includes a 
desktop and task manager component that can be optionally included or 
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replaced. The task manager component includes the following basic 
functionality: 

• An Active Tasks list of all the currently running, top-level 
applications; 

5 • A Run button that allows a user to launch a software 

application; 

• A Switch To button that allows a user to switch to an 
application selected in the Active Tasks listbox. 

• An End Task button that allows a user to terminate an 
1 0 application selected in the Active Tasks listbox. 

• A Cancel button that allows a user to close the Task-Manager 
window. 

• Monitors the level of main battery and backup battery power 
(for battery-operated target platforms) and displays an 

1 5 appropriate warning dialog box. 

• Monitors system memory usage in the system and svnds a 
message to all top-level windows when the available systcn? 
memory drops below a specific threshold. This allows 
applications to respond to the message by reducing their 

20 memory usage as much as possible. 

The Add-on Technologies module 224 allows an embedded system 
developer to optionally include components such as OLE/COM automation that 
supports development of ActiveX-based applications, an active desktop shell and 
an Internet browser. Other components that can be included are Visual Basic 
25 run-time and Java script, and a subset of the Microsoft Foundation Classes 
(MFC). A further optional component that can be provided is a handwriting 
recognition engine with associated APIs. In one embodiment of the invention, 
handwriting applications interface with a touch sensitive input device through a 
component providing a software interface to the touch sensitive device. 
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The kernel module 214 represents the base operating system functionality 
that must be present on all platforms. The kernel module includes memory 
management, process management, exception handling, and support for 
5 multitasking and multithreading. 

In one embodiment of the invention, the kernel 214 is designed 
specifically for small, fast, embedded devices. In this embodiment, the kernel 
supports a single 4GB address space (a 2GB virtual address and a 2GB physical 
address range). In an embodiment of the invention, this 4GB address space is 
] 0 divided into 33 "slots", each of which has a size of 32MB. The kernel protects 
each process by assigning each process to a unique, open slot in memory. The 
invention, however, is not limited to any particular physical or virtual address 
space or slot size, and other sized may be chosen as those of skill in the art will 
recognize. 

1 5 The kernel 2 1 4 protects applications from accusing mvndky o-.:-sitie of 

their allocated slot by generating an exception. Applications can check for.and 
handle such exceptions by using the try and except Windows CE functions. In 
one embodiment of the invention, the system is limited to 32 processes, but the 
number of threads running in a process is limited only by the amount of available 

20 memory. Those of skill in the art will appreciate that other values for the 

maximum number of processes could be chosen. 

The file system module 218 contains the functions that support persistent 

storage on the embedded system target platform. This storage is referred to as 

the "object store" and includes three different ways to store user data: 

25 • The file system. The file system typically supports common file 

manipulation functions, such as functions to create files and 
directories, read and write to files, and retrieve file and directory 
information. 
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The registry. The system registry is similar to the registries of the 
Windows 95 and Windows NT operating systems. The registry for 
all applications, including the applications bundled in ROM, is stored 
in the object store. 

The Database API. The operating system, in one embodiment of the 
invention, has its own structured storage to offer an alternative to 
exposing user and application data in files or the registry. For 
example, a database is useful for storing raw data that an application 
will process before displaying to the end-user. Hand-held PC 
applications typically store schedule and contact information in 
databases. 

In one embodiment of the invention, the file system managed by file 
system module 218 is a transactioned system to reduce the possibility that data 
will be lost due to a critical failure, such as loss of power. Additionally, in one 
embodiment of the invention, the file system module 218 implements a scheme 
(transactioned) of "mirroring" to minror or track file system operations (not 
transactioned). The purpose for this implementation is to be abic Jo restore a file 
system volume in the case that power is lost during a critical sequence of 
operations being performed on the volume. 

In one embodiment of the invention, the operating environment combines 
the Win32 User and GDI (Graphics Device Interface) libraries into a GWES 
(Graphics, Windowing, and Events Subsystem) module 212. The event manager 
and window manager are analogous to Win32 User, and the Win32 GDI is 
replaced with a smaller GDI more suitable to embedded systems. The GWES 
module 212 includes multiplatform GDI components (supporting an associated 
display driver) that support color and grayscale display, palette management, 
TrueType fonts, Raster fonts, cursors, and printer device contexts (DCs). 

The GWES module 212 also supports a window management component 
that provides API functions tailored for the smaller display sizes typical of 
embedded operating systems. 



WO 99/49394 



WO 99/49394 



15 



PCT/US99/06223 



The operating environment of various embodiments of the invention is 
event-driven. GWES module includes components to handle events, which in 
one embodiment of the invention are implemented as messages. 

Communications module 216 includes a variety of communications 
component options to support communications hardware. This includes serial, 
parallel, and network (wired and wireless) communications. Communications 
module 2 1 6 includes the following selectable communications features: 

• Serial I/O support 

• Networking support including: 

■ NDIS 4.0 for local area networking 

■ PPP and SLIP for serial link and modem networking 

■ Client-side Remote Access Server (RAS) 

■ Internet protocols 

■ Telephony API (TAPI) 

■ PC Card support 

■ Infrared transceiver support 

In-one embodiment of the invention, an embedded systems designer must 
develop the OEM adaptation layer 208 to create the platform specific kernel 
module 214. The OEM Adaptation Layer (OAL) module 208 allows an 
embedded system developer to adapt the operating system for a specific target 
platform by creating a thin layer of code that resides between the kernel module 
214 and the target platform hardware 202. The OAL module 208 is specific for 
a particular CPU and target platform. 

The OAL module 208 includes interfaces such as the following: 

• Interrupt service routine (ISR) handlers to support device 
drivers 

• Real-time clock (RTC) 

• Interval timer (used for the scheduler operation) 

In one embodiment of the invention, the RTC and interval timer does not 
need to be adapted because it is provided on the CPU. In this case, these 
interfaces are implemented in the kernel module 214 rather than in the OAL 208. 
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In addition to managing such functions as timing and power, the primary 
purpose of the OAL is to expose the target platform's hardware 202 to the kernel 
module 214. That is, each hardware interrupt request line (IRQ) is associated 
with one interrupt service routine (ISR). When interrupts are enabled and an 
5 interrupt occurs, the kernel calls the registered ISR for that interrupt. 

Built in drivers 206 are device drivers that are linked with GWES module 
212 when building the operating system. Examples of such drivers are the 
notification LED driver or the battery driver. These drivers are called "built-in 
device drivers" because they ultimately form part of the same executable image 
as the rest of the operating system. Built-in device drivers each have a custom 
interface to the rest of operating system. 

Device Manager module 210 is a module that handles installable device 
drivers. In one embodiment of the invention, The Device Manager 210 performs 
the following tasks: 

• - Initiates ihe loading of a driver at system star; up, oi when it receives 
a notification that a third-party peripheral has b^eri attached to the 
target platform. For example, when a PC Card is inserted, Device 
Manager 210 will attempt to locate and load a device driver for that 
PC Card. 

• Registers special filesystem entries with the kernel that map the 
Stream 170 Interface functions used by applications to the 
implementation of those functions in an installable device driver. 

• Finds the appropriate device driver by obtaining a Plug and Play ID 
or by invoking a detection routine to find a driver that can handle the 
device. 

• Loads and tracks drivers by reading and writing registry values. 

• Unloads drivers when their devices are no longer needed. For 
example, Device Manager 210 will unload a PC Card device driver 
when the card is removed. 

In one embodiment of the invention, Installable Device Drivers 204 exist 
as standalone DLLs (Dynamic Link Library) that are managed by the Device 
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Manager 210. Installable device drivers 204 support some types of native 
devices, any peripheral devices that can be connected to the target platform, and 
any special purpose devices that are added to the platform. This covers devices 
such as modems, printers, digital cameras, PC Cards (also known as PCMCIA 
5 cards), and others. 

In one embodiment of the invention, installable device drivers 204 use a 
common interface by which their services are exposed to applications. This 
interface is the Stream I/O Interface. 

A description of the relationships between components, modules and the 
1 0 APIs they expose to applications is presented with reference to FIG. 3. A 
module 308 is a major functional block of an operating environment such as 
operating system 200 of FIG. 2. Module 308 exposes an API 302 to applications 
such as application 226 of FIG. 2 that allows the application to interface and call 
methods or functions implemented by the module 308. 
15 Modules may optionally mc'tfds o>v: or more components 306. : 

Components 306 are groups of functions and data that provide capabilities on a 
smaller scale than modules 308. Like a module 308, a component 306 also 
exposes an API 304 that other applications, modules, and components may use 
to call methods or functions implemented by the component 306. 
20 As can be seen from the discussion above, the various embodiments of 

the invention provide advantages over prior systems. One benefit is that the 
operating system is modular. This allows an embedded system designer to 
create an operating environment that is optimized for their unique hardware 
development platform and application. The developer can select varying 
25 combinations of the above-described modules and components for inclusion in 
the operating environment. For example, a developer can build an embedded 
operating system that contains the kernel and a selected set of communications 
but does not provide a graphical user interface. Thus, the invention is not limited 
to any particular combination of modules and components. 
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The various embodiments of the invention also provides a mechanism for 
developers to conserve the limited memory resources of a typical embedded 
system, because only those modules and components having APIs that are 
necessary for the operating environment need be included. 

APIs in a Resource Limited Svstem 

The previous section presented a system level overview of modules and 
components included in a typical operating system for a system with limited 
resources. This section, along with the subjections that follow, present novel 
APIs and data structures related to the modules and components described 
above. The APIs detailed below are described in terms of the C/C++ 
programming language. However, the invention is not so limited, and the APIs 
may be defined and implemented in any programming language, as those of skill 
in the art will recognize. Furthermore, the names given to the API functions and 
parameters are meant to be descriptive of their function, however other names or 
identifiers could he associated- wEjS mt "functions anc parameters, as will be 
apparent to those of skill in the art. Six sets of APIs and data structures will be 
presented: Handwriting Recognition APIs, Position and Navigation APIs, 
Speech related APIs, Out of Memory APIs, Database APIs and Active Synch 
Data Structures. 

1. Handwriting Recognition APIs 

A handwriting recognition component is available in the Add-On 
Technologies module 224 (FIG. 2). The handwriting recognition component 
implements a handwriting recognition engine. In one embodiment of the 
invention, the engine receives "ink" in the fonn of a plurality of strokes on a 
touch sensitive screen. The strokes are then sent from applications to the engine 
using a variety of APIs. The engine then attempts to interpret the strokes as 
alphanumeric characters. The interpreted characters are returned to the 
application via an API. In one embodiment of the invention, the characters are 
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interpreted as English language characters. In alternative embodiments of the 
invention, the characters are interpreted in other languages. 

The handwriting recognition component is particularly useful in 
embedded systems that have a touch sensitive display, but no keyboard. 
5 Applications that require alphanumeric input can use the characters received 
from the engine as if they had been typed at a keyboard. 

Further details on the APIs used by applications that interface with a 
handwriting recognition engine are presented in the sub-section entitled 
"Detailed Description of a Handwriting Recognition API." 

10 

2. Position and Navigation APIs and Data Structures 

A Position and Navigation component is available in the Add-On 
Technologies module. The Position and Navigation component allows an 
application to interface with, a positioning device (also referred to as a 

15 2 positionirig-and navigation device) such as an Apollo GPS system. Such an 

interface is useful when the embedded system is located in a mobile article such 
as an automobile or truck. In one embodiment of the invention, the embedded 
system is the AutoPC. 

Further details on the APIs for the Position and Navigation module are 

20 found in the sub-section entitled "Detailed Description of a Position and 

Navigation API " Also, further details on data structures used by the Position 
and Navigation Module and related APIs are found in the sub-section entitled 
"Detailed Description of Data Structures for a Position and Navigation System." 

25 3. Speech Related APIs 

The Add-On Technologies module contains several speech-related 
components that expose APIs for application use. These components include a 
text-to-speech component, a voice-to-text component, and a voice command 
component. In genera], these components are intended for environments where 
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input and output devices are limited, and where a user's interaction with the 
embedded system is via speech. An example of such an environment is the 
AutoPC. Because the driver must use their hands in the operation of the 
automobile, interaction with the AutoPC is via a speech interface, where inpulj 
commands are spoken by the user, and output from the PC is converted from text 
to speech. 

Further details on the text-to-speech APIs are presented in the sub-section 
entitled "Detailed Description of a Speech-to-Text API/' Further details on the 
voice command and speech to text APIs are presented in the sub-seciions entitled 
"Detailed Description of a Voice Command API", "Detailed Description of Data 
Structures for a Voice Command API, and "Detailed Description of a Voice 
Command API for an AutoPC." 

4. Out of Memory API 

The Out of Memory API is a component of the GWES nioduVfc." "This 
component allows an embedded system developer to replace rbe defsulJ action 
that occurs when the operating system detects that the system is running out of 
available memory in which to run applications or place data. 

The Out of Memory component is significant to an operating system 
intended for limited resource environments, because the condition is more likely 
to occur in an embedded system than in a desk-top system. The API exposed 
provides a standardized way for the operating system to call customized software 
that meets the specific needs of an embedded system developer. 

Further details on the out of memory API are presented in the sub-section 
entitled "Detailed Description of an Out-of-Memory API." 

5. Database API 

As discussed above in reference to FIG. 2, the file system module 218 
may optionally include a database component. The database component allows 
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applications to create and maintain databases as file system objects. 
Applications make calls to various API functions that maintain the database. 
These functions include functions that create new databases, open existing 
database, delete databases, seeks particular records in databases, read records 
5 from databases and write records to databases. In addition, the Database API 
includes functions that navigate through a list of databases of a given type. 
Further details regarding the Database API are presented in the sub-section 
entitled "Detailed Description of a Database API." 

10 6. ActiveSync Data Structures 

ActiveSync is a component available in the Add-On Technologies 
module. The ActiveSync component provides a service that allows applications 
to compare two objects to determine if one of the objects needs to be updated in 
order for the objects to be "synchronized", that is, the same. Typically the 
15 objects are file system objects containing appiiciti^-data.v Actix'^y/ic is 
particularly useful when applied to hand-held PCs. This is.b^:ause-the vser 
often will update data maintained in a file system object on the hand-held PC, 
and then need to update a file on a desk-top PC so that the two files contain the 
same data. For example, hand-held PCs typically provide an application such as 
20 a Personal Information Manager that maintains a database of information, 

including telephone numbers. If a user maintains a similar database of telephone 
numbers on both their hand-held PC and their desk-top PC, it is desirable that the 
two telephone directories reflect updates made to either the hand-held PC or 
desk-top PC database. ActiveSync allows a user to accomplish this. 
25 In one embodiment of the invention, several data structures are employed 

that enable ActiveSync to correctly compare and perform updates to 
corresponding objects. The first data structure is the CONFINFO data structure. 
This data structure is used to retrieve information about two potentially 
conflicting items. In one embodiment of the invention, an ActiveSync Server 
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presents the information in the CONFINFO data structure to a user via a 
dialogue box to allow the user to choose an option for resolving the conflict. 
Further details regarding the CONFINFO data structure are presented in the sub- 
section entitled "Detailed Description of Data Structures for a Synchronization 



5 API." 1 
A second data structure used by the Active Synch component is the 
OB JNOTIFY structure. The OBJNOTIFY data structure is used to notify the 
ActiveSync service provider that an object in the file system has changed or been 
deleted. Further details regarding the OBJNOTIFY data structure are presented 
10 in the sub-section entitled "Detailed Description of Data Structures for a 
Synchronization API." 
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Detailed Description of Data Structures for a Synchronization API 
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Chapter 106 
HREPLITEM 

5 The HREPLITEM structure is used as a handle to a data object 

stored by a client. It is used as a generic handle to refer to either 
HREPLOBJ or HREPLFLD. 

Syntax typedef struct JIEPLITEM FAR 'HREPLITEM: 

10 

At a Glance Header file: cesync.h 
Platforms: H/PC 
Windows CE versions: 2.0 and later 

15 Members HREPLFLD 

Handle to a data object stored by a client. 

HREPLFLD 

20 

The HREPLFLD structure is used as a handle to a folder stored 
by a client. 

Syntax typedef struct_REPLFLD FAR *HREPI FI D: 

25 

At a Glance Header file: cesync.h 
Platforms: H/PC 
Windows CE versions: 2.0 and later 

30 Members HREPLFLD 

Handle to a folder stored by a client. 



HREPLOBJ 

35 

The HREPLOBJ structure is used as a handle to an object stored 
by a client. 

Syntax typedef struct_REPLOBJ FAR *HREPLOBJ: 

40 

At a Glance Header file: cesync.h 
Platforms: H/PC 
Windows CE versions: 2.0 and later 

45 Members HREPLITEM 

Handle to an object stored by clients. 
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CONFINFO 

The CONFINFO structure is used to retrieve information about 
. two conflicting items. The server presents this information to the 
5 user via a dialog box so the user can choose an option for 

resolving the conflict. 

Syntax typedef struct tagConflnfo { 

UINT cbStruct; 
10 HREPLFLD hFolder; 

HREPLITEM hLocalltem; 
HREPLITEM hRemoteltem; 

char szLocalName[MAX_OBJTYPE_NAME]; 
char szLocalDesc[512]; 
15 char szRemoteName[MAXJ3BJTYPE_NAME]; 

char szRemoteDesc[512]; 
} CONFINFO, *PCONFINFO; 

At a Glance Header file: cesynch 
20 Platforms: H/PC 

Windows CE versions: 2.0 and later 

Members cbStruct 

Size of this structure. 
25 hFolder 

Handle representing the folder where the objects are 
stored. 
hLocalltem 

Handle representing the local object. 
30 hRemoteltem 

Handle representing the remote object. 
szLocalName 

Name of the local object client would like to show to the 
user. 

35 szLocalDesc 

Description of the local object client would like to show to 
the user. 
szRemoteName 

Name of the remote object client would like to show to the 
40 user. 

szRemoteDesc 

Description of the remote object client would like to show 
to the user. 
See Also IReplStore::GetConflictlnfo 
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OBJNOT1FY 



10 



15 



At a Glance 



20 



The OBJNOTIFY structure is used to notify the ActiveSync 
service provider that an object in the Windows CE file system has 
changed or been deleted. 

typedef struct tagObjNotify{ 
UINT cbStruct; 

OBJTYPENAME szOBJTypefMAX OBJTYPE_NAME]; 
UINT uFlags; 
UINT uPartnerBit; 
CEOID oidObject; 
CEOIDINFO oidlnfo; 
UINT cOidChg; 
UINT cOidDel; 
UINT *poid 
} OBJNOTIFY, *POBJNOTIFY; 



Header file: 
Platforms: 

Windows CE versions: 



cesync.h 
H/PC 

2.0 and later 



25 



30 



35 



40 



45 



Members obstruct 

Input. Size of the structure in bytes. 
SzObjType 

Input, the object type name. 

uFlags 

Input Flags. 
ONF_FILE 

the object is a file. 
ONF_DIRECTORY 

the object is a directory. 
ONF_DATABASE 

the object is a database. 
ONFRECORD 

the object is a record. 
ONFCHANGED 

set if the file system object is changed. 
ONF_DELETED 

set if the file system object is deleted. 
ONF_CLEAR_CHANGE 

client should clear the change bit for the object 

whose object identifier is pointed at by poid. 
ONF_C ALL_B A CK 

output. Client asks server to call ObjectNotify two 

seconds later. 
ONF_CALLING_BACK 

set if this call is a result of ONF_CALL_B ACK 

being set earlier. 
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uPartnerBit 

Input. It is J if the desktop currently connected is partner 
#1, and it is 2 if the desktop is partner #2. 
oidObject 

Input. This is the OID of the file system object, 
representing a file, a database, or a database record, i 
Oidlnfo 

Input. Stores information about the object (if the object 
has not been deleted). 
cOidChg 

Output. When ONF_CHANGED is set, this is the number 
of oid's that should be replicated. Set to 0 if no object 
should be replicated because of this change. 

When both ONF_CHANGED and ONF_DELETED are 
not set, this is the number of oid's in the first part of the 
list for objects that are changed. 
cOidDel 

Output. When ONF_DELETED is set, this is the number 
of deleted oids that should be replicated. Set to 0 if no 
object should be replicated because of this delete. 

Wh^n both ONF_CHANG£D and ONF_DELETHD are 
not set, this is the number of oids in the later part of Ae 
list for objects that are not changed. 

poid 

Output. Points to an array of oid's that should be marked 
as needs to be replicated first cOidChg elements are for 
the changed objects, the last cOidDel elements are for the 
deleted objects Note that, memory pointed to by this 
pointer is owned by the ActiveSync service provider. It 
will not be freed by replication. 

This structure is passed to the ObjectNotify function to inform the 
provider that an event that changes or deletes an object in the 
Windows CE file system has occurred. The provider should 
return, via this structure, how many replication objects have 
changed or been deleted because of this change or deletion to a 
file system object. 

When ONFJTHANGED is set, cOidChg is the number of object 
id's in the list that should be synchronized (cOidDel is not used). 

When ONF_DELETED is set, cOidDel is the number of deleted 
object id's in the list that should by synchronized (cOidChg is not 
used). 

ObjectNotify 
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OBJUIDATA 

The OBJUIDATA structure is used by 

IReplStore::GetObjTypeUIData to send Ul related data about an 
5 object type to the Store. 

Syntax typedef struct tagObjUlData{ 

UINT " cbStruct; 

HICON hlconLarge; 
10 HICON hlconSmall; 

char szName[M AX_P ATH] ; 

char szSyncText[MAX_PATH]; 

char szTypeText[80]; 

char szP!TypeText[80]; 
15 } OBJUIDATA, *POBJUIDATA; 

At a Glance Header file: cesync.h 
Platforms: H/PC 
Windows CE versions: 2.0 and later 

20 

Members cbStruct 

The size of this structure. 
hlconLarge 

The handle of a large icon used in the list view display of 
25 the H/PC Explciev. 

hlconSmall 

The handle of a small icon used in the list view display of 
the H/PC Explorer. 
szName 

30 Text displayed in the "Name" column of the H/PC 

Explorer. 
szSyncText 

Text displayed in the "Sync Copy In" column of the H/PC 

Explorer. 
35 szTypeText 

Text displayed in the "Type" column of the H/PC 

Explorer. 
szPlTypeText 

Plural form of text displayed in the "Type" column of the 
40 H/PC Explorer. 

See Also IRep3Store::GetObjTypeUIData 
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REPLSETUP 

The REPLSETUP structure is used to initiate the object handler. 

5 Syntax typedef struct tagReplSetup{ 

UINT cbStruct; 
BOOL fRead; 
DWORD dwFlags; 
HRESULT hr; 

10 TCHAR szObjType[MAX_OBJTYPE_NAME]; 

IReplNotify *pNotify; 

DWORD oid; 

DWORD oidNew; 

IReplStore *pStore; 
15 HREPLFLD hFolder; 

HREPLITEM hltem; 
} REPLSETUP, *PREPLSETUP; 

At a Glance Header file: cesynch 
20 Platforms: H/PC 

Windows CE versions: 2.0 and later 

Members cbStruct 

Input. Size of this structure. 

25 fRead 

Input. TRUE if setting up for reading (serializing) the 
object. FALSE if setting up for writing (deserializing) the 
object. 
dwFJags 

30 Reserved by replication. 

Hr 

Output. Result of the read/write operation. 
szObjType 

Input. Name of the object type. 
35 pNotify 

Input. Pointer to IReplNotify::IUnknown interface. 

Oid 

Input. Object ID of the object. 
oidNew 

40 Output. Object ID of the new object. This is different 

from the oid if a new object was created during writing. 

pStore 

Input. Exists in desktop only. Points to IReplStore 
interface. This is unused for device side use. 
45 hFolder 

Input. Exists in desktop only. Handle of the folder. This 
is unused for device side use. 
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hltem 

Input or Output. Exists in desktop only. Handle of the 
object to be read or written. This is unused for device side 
use. 



5 



10 



See Also IReplObjHandler: :Setup 
STORE1NFO 



The STOREINFO structure is used to identify an instance of the 
store. 



Syntax typedef struct tagStorelnfo { 

15 UINT cbStmct; 

UINT uFlags; 
TCHAR szProgId[256]; 
TCHAR szStoreDesc[200]; 
UINT uTimerRes; 
20 UINT cbMaxStoreld; 

UINT cbStoreld; 
. LPBYTE . ipbS?oreId; 
* } STOREINFO, *PSTOREfNFO; 

25 At a Glance Header file: cesync.h 
Platforms: H/PC 
Windows CE versions: 2.0 and later 

Members cbStruct 
30 Size of this structure. 

uFlags 

Output. Combination of the followine flags: 

SCF_SINGLE_THREAD 

Set if the implementation only supports single 
35 thread operation. 

SCF_S1MTJLATE_RTS 

Set if the implementation wants to simulate 
detection of real-time change/deletes. 

szProgld 

40 Output. ProgID name of the store object. 

szStoreDesc 

Output. Description of the store, will be displayed to the 
user. 
uTimerRes 

45 Input/Output. Resolution of timer in microseconds. 5000 

by default. Applicable only when SCF_SIMULATE_RTS 
is set in uFlags. 
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cbMaxStoreld 

Input. Max. size of the store ID that can be stored in 

buffer pointed by IpbStoreld. 
cbStoreld 

5 Output. Actual size of the store ID stored in buffer 

pointed by IpbStoreld. 
IpbStoreld 

Output pointer to a buffer of anything that uniquely 
identifies the current store instance, for example, a 
10 schedule file. 

Remarks Note that calls to the IReplStore interface methods can come from 
different threads. If the client does not support multi -threading, it 
must s&fSingleThreadOnly to FALSE, so the server will serialize 
1 5 the calls to the methods and make them all come from the primary 

thread of the application. szStoreDesc can have a value such as 
"Schedule+File" It is displayed to the user whenever the store ID 
indicates a different store, such as a different Schedule+file, has 
been installed. 

10 

See Also IReplStore::GetStoreInfo 



DEV1NFO 



25 



35 



The DEVINFO structure is used to store infonnation about a 
device. 



typedef struct tagDevInfo { 
30 DWORD pid; 

char szName[MAX_PATH]; 
char szType[80]; 
char szPath[MAX_PATH] 
} DEVINFO, *PDEVINFO; 



At a Glance Header file: 
Platforms: 



Windows CE versions: 
40 Members pid 

Device identifier. 
szName 

Device name. 

szType 

45 Device type. 

szPath 

Device path. 
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OBJTYPE1NFO 

The OBJTYPEINFO structure is used to store information about 
an object type. 

5 

fypedef struct tagOBJTypelnfo { 



10 



15 



UINT 


cbStruct; 


OBJTYPENAMEW 


szObjType; 


UINT 


uFlags; 


WCHAR 


szName[80] 


UINT 


cObjects; 


UNIT 


cbAllObj; 


FILETIME 


ftLastModified 



} OBJTYPEINFO, *POBJTYPEINFO; 



At a Glance Header file: 
Platforms: 



Windows CE versions: 

20 Members cbStruct 

Input. The size of the structure in bytes. 
szObjtype 

Input. The object type na?>te. 

uFlags 

25 Reserved. 

szName 

Output. The name of a file system object storing all these 
objects. 
cObjects 

30 Output. The number of existing objects of this type. 

cbAllObj 

Output. The total number of bytes used to store existing 
objects. 
ftLastModified 

35 Output. The last time any object was modified. 
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Detailed Description of a Synchronization API 
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Chapter 8 

IRepINotify : lUnknown 



10 



At a Glance 



An ActiveSync service manager implements the 
IReplNotify:Notify interface, which can be used by an 
ActiveSync service provider to notify the ActiveSync service 
manager of certain events taking place in the ActiveSync service 
provider's store. 



Header file: 
Platforms: 

Windows CE versions: 



Cesynch 
H/PC 

2.0 and later 



Methods 



Description 



IRepINotify: :GetWindow 



IReplNotify::OrutemCoropleted 

IRepINotify: :OnJtemNotify 

IRepINotify: :QueryDevice 
IRepINotify: :SetStatusText 

IUnknown::AddRef 



lUnkno wn : : Qu erylnt erface 



Obtains a handle to the 
window that must be used as 
a parent for any modal dialog 
or message box that an 
ActiveSync service provider 
wants to display. 
Used internally by the 
ActiveSync service manager. 
An ActiveSync service 
provider should not call this 
explicitly. 

Notifies the ActiveSync 
service manager that an item 
has been created, deleted, or 
modified. 

Used to ask for information 
about a device. 
Sets the text to be displayed 
on the Explorer Window 
status control. 
Increments the reference 
count for an interface on an 
object. It should be called for 
every new copy of a pointer 
to an interface on a specified 
object. 

Returns a pointer to a 
specified interface on an 
object to which a client 
currently holds an interface 
pointer. This method must 
call RJnknown::AddRef on 
the pointer it returns. 
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IUnknown::Rcleasc ~~ Decrements the reference 

count for the calling interface 
on an object. If the reference 
count on the object falls to 0, 
the object is freed from 
; memory. 

Remarks The IReplNotify : IUnknown interface is implemented and 
exposed by the ActiveSync service manager. If the store is 
capable of detecting changes and deletions to the objects as they 
5 occur, an ActiveSync service provider should use the interface to 

notify the ActiveSync service manager of these changes and 
deletions. This is more efficient than enumerating the changes 
and comparing time stamps. 

10 

IRepINotify::GetWindow 

The IReplNotify: :Get Window method obtains a handle to the 
window that must be used as a parent for any modal dialog or 
15 message box that an ActiveSync service provider wants to 

•„.-■„ • display. . . 

Syntax HRESULT GeiWindow( 

UINT uFlags 
20 ); 

At a Glance Header file: Cesynch 
Platfonns: H/PC 
Windows CE versions: 2.0 and later 



25 



30 



Parameters uFlags 

Reserved; always 0. 
See Also IReplNotify 



]ReplNotify::OnItemCompleted 



The IReplNotify: :OnItemCompleted method is used internally by 
35 th e ActiveSync service manager. An ActiveSync service provider 

should never call this method explicitly. 

Syntax HRESULT OnObjectCompleted( 

PREPLSETUP pSeiup 
40 ); 
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36 

At a Glance Header file: Cesync.h 

Platforms: H/PC 

Windows CE versions: 2.0 and later 

Parameters pSetup 

Pointer to a REPLSETUP structure. 
See Also IReplNotify 



IReplNotify::OnItemNotify 



The IReplNotify::OnItemNotify method notifies the ActiveSync 
service manager that an object has been created, deleted, or 
15 modified. 

Syntax HRESULT OnItemNotify( 

UINTwCWe, 
LPSTR IpszProgld, 
20 LPSTR IpszObjType, 

HREPLITEM hltem, 
ULONG ulFlogs 

); 

25 At a Glance Header file: Cssvnc.h 

Platfonns: H/PC 

Windows CE versions: 2.0 and later 

Parameters uCode 
30 Code that describes what happened. Possible values 

include the following: 
RNC_CRE ATED 

Object was created. 
RNC_M ODIFIED 
35 Object was modified. 

RNC_DELETED 

Object was deleted. 
RNC_SHUTDOWN 

The store has been shut down. Windows CE 
40 Services should unload the module immediately. 

IpszProgld 

Programmatic identifier of the store. 
IpszObjType 

Name of the object type. 

45 hltem 

Handle of the concerned item. 

ulFlags 

Reserved. 
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Remarks If the store is capable of detecting changes and deletions as they 
occur, an ActiveSync service provider should call the 
IRep]Notify::OnItemNotify method immediately after any 
changes or deletions are detected. 

5 

See Also IReplNotify 
IReplNotifv::QueryDevice 

10 

The IReplNotify::QueryDevice method is used to ask for 
information about a device. 



Syntax 



15 



At a Glance 



20 



void QueryDevice( 
UINT uCode, 
LPVOID *ppvData 

); 

Header file: 
Platforms: 

Windows CE versions: 



Cesync.h 
H/PC 

2.0 and later 



Parameters uCode 

Input parameter. Possible values induce the following: 
25 QDC_SEL_DEV1CE 

Requests information for the selected device. In 
this case, *ppvData points to the DEVINFO 
structure containing the information for the device. 
QDC_CON_DEVICE 
30 Requests information for the connected device. In 

this case, *ppvData points to the DEVINFO 
structure containing the information for the device. 
QDC_SEL_DEV1CE_KEY 

Gets a registry key that can be used to store 
35 selected device-specific settings. In this case, 

*ppvData points to HKEY. The caller must close 
the registry key when its usage is over. 
QDC_C0N_DEV1CE_KEY 

Gets a registry key that can be used to store 
40 connected device-specific settings. In this case, 

*ppvData points to HKEY. The caller must close 
the registry key when its usage is over. 

ppvData 

Output parameter. Depending on uCode, this can point 
45 either to a DEVINFO structure or HKEY. 
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]ReplNotify::Se(StatusText 

The IReplNotify::SetStatusText method sets the text to be 
displayed on the Explorer Window status control. 

HRESULT SetStatusText ( 
LPSTR IpszText 

); 

Header file: Cesync.h 

Platforms: H/PC 

Windows CE versions: 2.0 and later 

IpszText 

Pointer to a status text string. 

Status messages should be advisory only. Use modal dialog 
boxes or message boxes for information that requires user 
intervention. 

IReplNotify 



IRepJObjHandJer : lUnknown 

25 ... v 

The IReplObjHandler : IUnknown interface implements all 
required functions related to the serialization and deserialization 
of an object. 

30 At a Glance Header file: Cesync.h 
Platforms: H/PC 
Windows CE versions: 2.0 and later 

Methods Description 

]ReplObjHandler::DeleteObj Informs the ActiveSync 

service provider that an object 
should be deleted. 
IReplObjHandler::GetPacket ActiveSync service provider 

implements this method to 
deserialize an object into one 
or more packets. These 
packets are sent between the 
Windows CE-based device 
and the desktop computer by 
the ActiveSync service 
provider. 

IReplObjHandler::Reset Resets the ActiveSync service 
, provider so all the resources 



5 

Syntax 



10 At a Glance 



Parameters 

15 

Remarks 



20 

See Also 
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IReplObjHandler::SetPacket 



IReplObjHandler::Setup 



IUnknown::AddRef 



RJnkno wn : : Query Int. erf ?.ce 



IUnknownrrRelease 



that the ActiveSync service 
provider used during the 
serialization or deserialization 
are freed 

ActiveSync service provider 
implements this method) to 
serialize one or more packets 
into an object. These packets 
are guaranteed to be in the 
same order as when they are 
sent. 

Sets up the ActiveSync 
service provider so it is ready 
to serialize or deserialize an 
object. 

Increments the reference 
count for an interface on an 
object. It should be called for 
every new copy of a pointer 
to an interface on a specified 
object. 

Return? a pointer :e 
specified interface on an 
object to which a client 
currently holds an interface 
pointer. This method must 
call IUnknown::AddRef on 
the pointer it returns. 
Decrements the reference 
count for the calling interface 
on an object. If the reference 
count on the object falls to 0, 
the object is freed from 
memory. 



10 



Remarks The IReplObjHandler : RJnknown interface encapsulates all 
functions needed to serialize or deserialize the objects. Any 
object can be deserialized into one or more data packets of any 
size. An ActiveSync service provider determines the number of 
packets and their sizes. These packets are exchanged between the 
Windows CE-based device and the desktop computer. The 
receiver of these packets is guaranteed to receive them in the 
exact same order as they are sent and the receiver can then 
serialize these packets back into an object. 
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IRepJObjHaDdier::De]e(eObj 



The IRep]ObjHandler::De]eteObj method informs the ActiveSync 
service provider that an object should be deleted. 

Syntax HRESULT DeleteObj( 

PREPLSETUP/tfe/wp 

); 



10 At a Glance 



15 



25 



Header file: 
Platforms: 

Windows CE versions: 



Cesync.h 
H/PC 

2.0 and later 



Parameters Setup 



Pointer to a REPLSETUP structure. 



Return Values NOERROR 

The operation was successful. 



20 Remarks 



The IReplObjHandler::DeleteObj method is called whenever the 
ActiveSync service manager determines that an object needs to be 
deleted.. Note that Setup and Re^ arc calkd-tjeforcWd *ftor 
this method. The ActiveSync service provider should delete the 
object specified in the given REPLSETUP structure. 



See Also IReplObjHandler 



30 



IRepIObjHandlerzrGetPacket 



35 



The ActiveSync service provider implements 
IReplObjHandler::GetPacket to deserialize an object into one or 
more packets. These packets are sent between the Windows CE- 
based device and the desktop computer by the ActiveSync service 
provider. 



40 



Syntax HRESULT GetPacket( 

LPBYTE VppbData, 
DWORD *pcbData, 
DWORD cbRecommend 

); 



At a Glance Header file: 
Platforms: 



45 



Windows CE versions: 



Cesynch 
H/PC 

2.0 and later 



Parameters IppbData 

Pointer to a pointer of the outgoing packet. 
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pcbData 

Pointer to a DWORD for the packet size. 
cbRecommend 

Recommended maximum size of the packet. 

Return Values NOERROR 

The operation successfully created one packet. 
RERR_BAD_OBJECT 

The operation failed to create one object. If the receiver 
10 does receive some of the earlier packets, they should be 

discarded. 
RWRN_LAST_PACKET 

A packet was successfully created, and it is the last one for 
the object. 

15 

Remarks During a deserialization of an object, the ActiveSync service 
manager calls the IreplObjHandler::GetPacket method 
continuously until RWRN_LAST_OBJECT or an error value is 
returned. The ActiveSync service provider determines how many 
20 packets are to be sent and the sizes of each packet. For efficiency, 

a packet size is recommended to be less than 8,000 bytes in size. 

Allocation and deallocation of memory for the packet is the 
responsibility of the ActiveSync service provider. An ActiveSync 
25 service provider sets ipvbDaia to ;hat pr inter and sets pcbDaia 

with the packet size. Typically, an ActiveSync service provider 
allocates a piece of memory of a known size in 
IReplObjHandler::Setup and frees it in IReplObjHandlen.Reset. 

30 See Also IRcplObjHandler::SetPacket 



IReplObjHandler::Reset 

35 The !ReplObjHandler::Reset method prompts the ActiveSync 

service provider to reset or free any resources used during the 
serialization or deserialization of an object. 

Syntax HRESULT Reset( 

40 FREPLSE7U? pSetup 

); 

At a Glance Header file: Cesync.h 

Platforms: H/PC 

45 Windows CE versions: 2.0 and later 

Parameters pSetup 

Pointer to a REPLSETUP structure. 
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10 



42 

Return Values NOERROR 

The operation was. successful. 

Remarks The !ReplObjHandler::Reset method is called once per object. 
See Also IReplObjHandler::Setup 

IReplObjHandIer::SetPacket 

The ActiveSync service provider implements SetPacket to 
serialize one or more packets into an object. These packets are 
guaranteed to be in the same order as when they are sent. 

15 Syntax HRESULT SetPacket( 

LPBYTE IbpData, 
DWORD cbData 

); 

20 At a Glance Header file: Cesynch 
Platforms: H/PC 

. . . Windows CE versions: ._ 2,0 and later 

Parameters IpbData "\ 
25 T Hovnier to the incoming packet. 

cbData 

Stores the packet size. 

Return Values NOERROR 
30 The packet was successfully used to deserialize the object. 

RERR_SKIP__ALL 

Failed to apply the packet toward the object; skip all 
remaining packets for the object. 

35 Remarks The IRepJObjHandler::SetPacket method is called continuously 
until the last packet is received. These packets are guaranteed to 
be received in the same number and order as they are created by 
IReplObjHandler::GetPacket. 

40 See Also IReplObjHandIer::GetPacket 



45 



IReplObjHandler::Setup 



The IReplObjHandler::Setup method sets up the ActiveSync 
service provider so it is ready to serialize or deserialize an object. 
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10 



15 



Syntax HRESULT Setup ( 

PREPLSETUP pSetup 

); 

At a Glance Header file: 
Platforms: 

Windows CE versions: 
Parameters pSetup 



Cesync.h 
H/PC 

2.0 and later 



Remarks 



See Also 



Pointer to a REPLSETUP structure, which contains 
information about the object to be serialized or 
deserialized. 

The IReplObjHandler::Setup method is called once per object. 
Necessary data is stored in the passed REPLSETUP structure. 

REPLSETUP 



20 IReplStore : lUnknown 



The IReplStore : lUnknown interface implemc- 
functions related tc the store. 



cih require;: 



25 



At a Glance Header file: 
Platforms: 



Windows CE versions: 



Cesync.h 
H/PC 

2.0 and later 



IReplStore Methods 



IReplStore::ActivateDialog 



IReplStore: :BytesToObject 



IReplStore::CompareItem 



IReplStore::CompareStoreIDs 



IR ep 1 S t or e : : Cop y Obj ect 



Description 



Activates an ActiveSync 
service provider-specific 
dialog box. 

Converts an array of bytes to 
a HREPLOBJ, which can be 
either a HREPLITEM or 
HREPLFLD, when loading. 
Compares the specified 
handles using entry 
identifiers, such as file names 
or record numbers. 
Compares two store 
identifiers to determine of 
they are equal. 
Copies one HREPLOBJ, 
which can be either a 
HREPLITEM or 
HREPLFLD, over to another. 



SUBSTITUTE SHEET (RULE 26) 



WO 99/49394 



44 



PCT/US99/06223 



!ReplStore::FindFirstItem 

IReplStoreiFindltemClose 
IRep]Store::FindNextItem 

IReplSlore::FreeObject 

IReplStore::GetConflictInfo 

IReplStore::GetFolderInfo 

IReplStore::GetObjTypeUIData 

IReplStore:GetStoreI«fo-- - ^ 
IReplStore: initialize 
IReplStore::JsFolderChanged 

IRep]Store::IsItemChanged 
IReplStore::IsItemRep]jcated 

IReplStore::IsValidObject 
JReplStore::ObjectToBytes 

IReplStore::RemoveDuplicates 
!Rep]Store::ReportStatus 



Returns a new HREPLITEM 
of the first object in the given 
folder, if there's any. 
Completes the Find operation 
in the given folder. 
Returns a new HREPLITEM 
of the next object in the given 
folder, if there's any. 
Frees the specified 
HREPLOBJ handle. 
Gets information about two 
conflicting objects. 
Returns a HREPLFLD for 
folder, given the object type 
name. Also returns a pointer 
to the IReplObjHandler of the 
given object type. 
Sends user interface (Un- 
related data about an object 
type to the ActiveSync 
service manager. 
Gets fefbrm^tion abbrii the 
curreni 'Store instance. 
Initializes the ActiveSync 
se; vice provider. 
Determines if any object in a 
specified folder has been 
changed since the method was 
last called. 

Determines if the item has 
changed. 

Determines if the item should 
be replicated using 
ActiveSync service provider- 
defined rules. 

Determines if the specified 
handles are valid. 
Converts the HREPLOBJ, 
which can be either a 
HREPLITEM or 
HREPLFLD, to an array of 
bytes when saving. 
Finds and removes duplicated 
objects from the store. 
ActiveSync service manager 
is reporting to the store about 
the status of the 
synchronization. 
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IReplStore::UpdateItem 



IUnknown::AddRef 



IUnknown::Querylnterface 



IUnknown "Release 



Updates the object's time 
stamp, change number, and 
other information that is 
stored in the specified handle. 
Increments the reference 
count for an interface on an 
object. It should be calledfor 
every new copy of a pointer 
to an interface on a specified 
object. 

Returns a pointer to a 
specified interface on an 
object to which a client 
currently holds an interface 
pointer. This method must 
call IUnknown::AddRef on 
the pointer it returns. 
Decrements the reference 
count for the calling interface 
on an object. If the reference 
count on the object falls to 0, 
the objects freed from 
memory. 



Remarks 



The IRepiSiore r-IUnkiiov.^ interface encapsulates all functions 
needed to access the objects in the store. A handle of type 
HREPLITEM identifies each object in the store. 



IReplStore::Aetiva1eDia!og 

0 The IReplStore::ActivateDialog method activates an ActiveSync 

service provider-specific dialog box. 

Syntax HRESULT ActivateDialog( 

UINTuDlg, 
5 HWND hwndParent, 

HREPLFLD hFolder, 
IEnumReplItem *penum 

); 

0 At a Glance Header file: Cesync.h 

Platforms: H/PC 

Windows CE versions: 2.0 and later 

Parameters uDlg 

Identifies the dialog box to be activated. 
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hwndParent 

Handle to the window that should be used as parent for the 
dialog box. 
hFolder 

5 Handle to a folder. 

penum 

Pointer to an enumerator of HREPLITEM for objects 
stored in the folder. 

Return Values NOERROR 

User selected OK to save the chanees made. 
RERRCANCEL 

User selected CANCEL to ignore the changes made. 
RERR__SHUT_DOWN 

User selected OK to save the changes made. The 
ActiveSync service manager must be closed now because 
of these changes. 
RERRJUNLOAD 

User selected OK to save the changes made. Replication 
modules must be unloaded so the change can take effect 
EJSfOTIMPL 
-■ ; ... The requested diaiog box is not implemented. 

The IReplStore: :ActivriteDialog method is used to activate dialog 
boxes options for each object type;' ReplDialogs contains the list 
of dialog boxes that can be activated. An ActiveSync service 
provider can return E_NOTIMPL if it does not implement a 
particular dialog box. An enumerator of the HREPLITEM 
contained in the specified folder is passed in. The ActiveSync 
service provider should use this enumerator to enumerate all 
items in the folder. 

See Also IReplStore 

35 

]ReplStore::BytesToObject 

The IReplStore: :BytesToObject method converts an array of 
bytes to an HREPLOBJ, which can be HREPLITEM or 
40 HREPLFLD, when loading. 

Syntax HREPLOBJ BytesToObject( 

LPBYTE Ipb, 
UINTd? 
45 ); 

At a Glance Header file: Cesync.h 
Platforms: U/PC 
Windows CE versions: 2.0 and later 



Remarks 

25 



30 
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Parameters Ibp 



cb 



47 



Pointer to a buffer where the array of bytes should be 
stored. This parameter can be NULL. 

Size of the buffer. 



Remarks The IReplStore::BytesToObject method is used to convert a series 
of bytes into an item or folder handle. BytesToObject returns the 
10 new handle. 

See Also IReplStore::ObjectToBytes 



15 IReplStore::CompareItem 



The IReplStore::CompareJtem method compares the specified 
handles using entry identifiers, such as file names or record 
numbers. 

Syntax int CompareItem( 

HREPLITEM hhewj, ,,-....„..,,„-.. - - 

HREPLiTEM hhcm2 

h 



20 



At a Glance Header file: 
Platforms: 

Windows CE versions: 
30 Parameters hheml 



35 



40 



45 



Cesynch 
H/PC 

2.0 and later 



hhem2 



Return Values 0 



Handle to the first object. The ActiveSync service 
manager guarantees this handle is one of those returned by 
FindFirstltem or FindNextltem. 

Handle to the second object. The ActiveSync service 
manager guarantees this handle is one of those returned by 
FindFirstltem or FindNextltem. 



These two handles represent the same object. 
The first object is bigger than the second object. 
The first object is smaller than the second object 



See Also HREPLJTEM. IReplStore::IsItemChanged 
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10 



15 



20 



25 



30 



)ReplStore::CompareStoreIDs 



35 



The IReplStore::CompareStorelDs method compares two store 
identifiers to determine if they are equal. 



Syntax HRESULT CompareStoreIDs( 

LPBYTE IpbID], 
UINT cblDl, 
LPBYTE !pbJD2, 
UINT cbID2 

); 



At a Glance Header file: 
Platforms: 



Parameters 



Windows CE versions: 
IbpIDl 



Cesynch 
H/PC 

2.0 and later 



cblDl 



lpbID2 



cblD2 



Pointer to the first store identifier. 
Size of the first store identifier. 
Pointer to the second siorc identifier. 
Size of the second store i;ien:ifier. 



Return Values 0 
1 

-1 



These store identifiers represent the same store. 
The first store is bigger than the second store. 
The first store is smaller than the second store. 



Remarks Replication calls the IReplStore::CompareStoreIDs method 

whenever it needs to know if the current store is different than the 
one it last replicated with. The store identifiers passed are always 
obtained from the STOREINFO structure set by the 
!ReplStore::GetStoreInfo method. 

40 See Also IReplStore::GetStoreInfo, STOREINFO 



45 



IRep!Store::CopyObject 



The !Rep]Store::CopyObject method copies one HREPLOBJ, 
which can be either a HREPLITEM or HREPLFLD, over to ' 
another. 
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Syntax BOOL CopyObject( 

HREPLOBJ hObjSrc, 
HREPLOBJ hObjDst 

); 

5 

At a Glance Header file: Cesync.h 

Platforms: H/PC 

Windows CE versions: 2.0 and later 

10 Parameters hObjSrc 

Handle to the source. 
hObjDst 

Handle to the destination. 

1 5 Return Values TRUE 

The operation was successful. 

FALSE 

The operation failed. A possible reason is that the two 
handles are of different types or of different sizes. 

20 

Remarks The IReplStorerrCopyObject method is used to copy the contents 
of a speeded handle to another. Any resource allocated in the 
source must be freed before they are overwritten, and any 
resource in the destination should be reset so it is not freed after 
25 the assignee-;.; to the source. CopyObject is always called whin 

the ActiveSync service manager detects that an object has been 
modified since the last replication and its contents must therefore 
be updated from the modified handle returned by the ActiveSync 
service provider from FindNextltem or FindNextltem. 

30 

See Also IReplStore 



35 IRepIStore::FindFirstItem 

The IReplStore::FindFirstItem method returns a new handle to the 
first object in a specified folder, if there is any. 

HRESULT FindFirstItem( 
HREPLFLD hFolder, 
HREPLITEM *phJtem 9 
BOOL *p/Exist 

); 

Header file: Cesync.h 

Platforms: H/PC 

Windows CE versions: 2.0 and later 



40 Syntax 



45 

At a Glance 
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Parameters hFolder 

Handler to a folder. 

phltem 

Output pointer to a handle of the first object in the folder. 

5 pfExist 

Output pointer to a Boolean value that is set to TRUE if 
there is an object in the folder. 

Return Values E_FAJL 

There are problems with the enumeration. Replication 
should ignore the folder. 
NOERROR 

A new HREPLITEM was created for the first object in the 
folder and its pointer has been returned. 

The IReplStore::FindFirstItem method works together with 
FindNextltem and FindltemClose to enumerate all items in a 
specified folder. FindFirstltem and FindNextltem are the only 
methods in IReplStore that can create HREPLITEM for the items. 
All HREPLITEM structures passed by the ActiveSync service 
manager are guaranteed to be originally created from these two 
methods. It is possible that/before FindltemClose fifcallfri; i - : - : 
different tliread calls methods like DeleteObject that vvrlte to "flic 
store. Therefore, it is important for the ActiveSync service 
provider to have some sort of thread synchronization berween this 7 
method and the methods that write to the store. A typical 
ActiveSync service provider would use critical section to make • 
sure that, during the time between calls to FindFirstltem and 
FindltemClose, no write to the store is permitted. 

See Also HREPLITEM, IReplStore: :FindItemClose, 
IReplStore: :FindNextItem 

35 

IRep)Store::FindItemCIose 



Remarks 



20 



25 



The IReplStore::FindItemClose method completes the folder 
enumeration. 

40 

Syntax HRESULT FindItemClose( 

HREPLFLD hFolder 

); 

45 At a Glance Header file: Cesync.h 

Platforms: H/PC 

Windows CE versions: 2.0 and later 
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Parameters hFolder 

Handle for .the folder being enumerated. 

Return Values NOERROR 
5 The operation was successful. 

Remarks The IRep]Store::Find]temClose method works with FindFirst)tem 
and FindNextltem to enumerate all items in a specified folder. 
An ActiveSync service provider can do whatever it needs to 
10 complete the enumeration, for example, free memory and delete 

temporary objects. 



15 



See Also HREPLITEM, IReplStore::FindFirstltem, 
IReplStore::FindNextItem 



IRepIStore::FindNexlItem 



The IReplStore::FindNextItem method returns a new item handle 
20 10 *c next object in a specified folder, if there is any. 

Syntax HRESULT FindNexiltem( : ~ .-- 

: HREPLFLDF hFolder, " • "■" 
HREPLITEM *phJtem 
25 BOOL*p/Exist 

); 

At a Glance Header file: Cesynch 

Platforms: H/PC 

30 Windows CE versions: 2.0 and later 

Parameters hFolder 

Handle to a folder. 

phltem 

35 Output pointer to a handle of the next object in the folder. 

pfExist 

Output pointer to a Boolean value that is set to TRUE if 
there is an object in the folder. 

40 Return Values EFAIL 

There are problems with the enumeration. Replication 
should ignore the folder. 
NOERROR 

A new HREPLITEM was created for the next object in the 
45 folder and its pointer has been returned. 

Remarks The IReplStore::FindNextltem method works with FindFirstltem 
and FindltemClose to enumerate all items in a specified folder. 
FindNextltem and FindFirstltem are the only methods in 
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IReplStore that can create HREPLITEM structures for the 
objects. All HREPLITEM structures passed by the ActiveSync 
service manager are guaranteed to be originally created from 
these two methods. 

5 

See Also HREPLITEM, IReplStore::FindFirstItem, 
IReplStore::FindItemClose 



10 IReplStore: :FreeObject 

The IReplStore::FreeObject method frees the specified 
HREPLOBJ handle. 

15 Syntax void FreeObject( 

HREPLOBJ hObject 

); 

At a Glance Header file: Cesync.h 

20 Platforms: H/PC 

Windows CE versions: 2.0 and later 

Parameters hObjeci 

Pointer to the handle of an object whose contents need to 
25 be freed. 



Return Values None. 

The IReplStore: :FreeObject method is used to free any memory 
pointers or delete any temporary objects that might have been * 
created during the life of the handle and must befreed when the 
handle dies. This handle could either be an HREPLITEM or 
HREPLFLD structure. 

35 See Also IReplStore 



IReplStore::GetConflictInfo 

40 

The IReplStore::GetConflictInfo method gets information about 
two conflicting objects. 

Syntax HRESULT GetConflictInfo( 

45 PCONFINFO pConflnfo 

); 



Remarks 

30 
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At a Glance Header file: Cesynch 

Platforms: H/PC 

Windows CE versions: 2.0 and later 

Parameters pConflnfo 

Pointer to the CONFINFO structure. 

Return Values NOERROR 

Information was retrieved successfully. 
RERRJGNORE 

This conflict should be ignored. The objects are identical. 

See Also IReplStore 



]RepIStore::GetFoIderinfo 



Syntax 



The IReplStore: :GetFolderlnfo method creates a new 
HREPLFLD of a folder for the specified object type name and 
returns a pointer to the IReplObjHandler interface that is used to 
serialize and deserialize all items in this folder. 

HRJESULT GetFolS Info( 
LPSTR IpszName, 
HREPLFLD "pkFolder, 
IUnknown **ppObj Handler 

); 



At a Glance 



Parameters 



Header file: 
Platforms: 

Windows CE versions: 



Cesync.h 
H/PC 

2.0 and later 



IpszName 

Name of the object type as taken from the registry. 
phFolder 

Output pointer to the handle of the folder. 
ppObjHandler 

Output pointer to a pointer to the IReplObjHandler 
interface. 



Return Values NOERROR 

The operation was successful. 

Remarks The IReplStore::GetFolderInfo method is the only method in 
IReplStore that creates or modifies a HREPLFLD structure for 
the folder. The ActiveSync service manager calls this method to 
get a folder handle for the specified object type. Object types are 
configured into the registry, where object type name and other 
relevant information about an object type are stored. Note that 
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the handle pointed to by phFolder may or may not be NULL 
when called. If phFolder points to a handle that has a NULL 
value, the ActiveSync service provider should create a new 
handle for the specified folder. If phFolder points to a pointer 
5 that has a value, the ActiveSync service provider should modify 

the data indicated by this handle. 



10 



15 



See Also IReplStore 



IRep)Store::GelObjTypeUIData 



The IReplStore::GetObjTypeUIData method sends user interface 
(Ul)-related data about an object type to the ActiveSync service 
manager. 



Syntax HRESULT GetObjTypeUIData( 

HREPLFLD hFolder 9 
POBJUIDATA pData 
20 ); 

At a Glance Header file; Cesync.h 

Platforms: ■ ■-. ; h/PC 

Windows CE versions: 2.0 and later 

25 

Parameters hFolder 

Input parameter. Pointer to a handle of a folder that 
contains the items. 

pData 

30 O ut Put parameter. Pointer to an OBJUIDATA structure. 

Return Values NOEJtROR 

User selected OK to save the changes made. 
E_OUTOFMEMORY 
35 The operation was unable to load required UI resources. 

See Also IReplStore 



40 

IReplStore: rGetStorelnfo 

The IReplStore: :GetStoreInfo method gets information about the 
current store instance. 

45 

Syntax HRESULT GetStoreInfo( 

PSTOREINFO plnfo 

); 
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At a Glance Header file: Cesync.h 

Platforms: H/PC 

Windows CE versions: 2.0 and later 

5 Parameters plnfo 

Pointer to the STOREINFO structure. 

Return Values NOERROR 

The STOREINFO structure was successfully returned. 
10 EJNVALIDARG 

The value ofcbStruct is not expected. 
E_POINTER 

The store is not initialized or there is a problem getting the 
required store identifier or lpbStored is NULL. 
15 EJ3UTOFMEMORY 

The value of cbMaxStoreld is too small. The size of the 
identifier is set in cbStoreld upon return. 

Remarks The ActiveSync service manager calls the 
20 IReplStore::GetStoreInfo method with IpbStoreld set to NULL 

for the first time. The ActiveSync service provider should then 
set cbStoreld to the size of the siore riemi£;er\ Ri:u5>;.£- 'heo 
calls GetStorelnfo again with an allocated buffer snd the size 
stored in cbMaxStoreld. 



See Also STOREINFO 



IReplStore:;]nitialize 



The IReplStore::Initialize method initializes the IReplStore 
ActiveSync service provider. 



Syntax HRESULT Initialize( 

35 IReplNotify *pReplNorijy 

UIN7 uFlags 

); 

At a Glance Header file: . Cesync.h 

40 Platforms: H/PC 

Windows CE versions: 2.0 and later 

Parameters pReplStatus 

Pointer to the IReplNotify interface. This parameter must 
45 beO. 

uFlags 

Flags passed to the store by the ActiveSync service 
manager. Possible values include the following: 
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ISF_SELECTED_DEVICE 

Set if the store is initialized for the selected device; 
otherwise, it is initialized for the connected device 
ISF_REMOTE_CONNECTED 
^ Set if the store is initialized during the remote 

connection; all user interface (UI) should be 
suppressed. 

Return Values NOERROR 
1 0 The operation was successful. 

See Also IReplStore 

1 5 IReplStore::lsFolderCbanged 

The IReplStore: :JsFolderChanged method determines if any 
object in a specified folder has been changed since the method 
was last called. 

HRESULT IsFoIderChanged( 
HREPLFLD h Folder. .. 
BbOI ^pfCfcnged 

); 

Header file: Cesynch 

Platforms: H/PC 

Windows CE versions: 2.0 and later 

hFolder 

Handle to a folder. 
pfChanged 

Pointer to a Boolean value that is set to TRUE if folder is 
changed. 
35 

Return Values NOERROR 

The operation completed successfully. The pfChanged 
parameter is set to TRUE if the folder is changed, or 
FALSE otherwise. 
40 RERR_SHUT_DOWN 

There was a serious error, and the ActiveSync service 
provider should shut down immediately. 
RERRJJNLOAD 

There was a less serious error, and replication modules 
45 must be unloaded. 

RERR_STORE_REPLACED 

The complete store was replaced. 



20 

Syntax 



25 

At a Glance 



30 Parameters 
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Remarks If the ActiveSync service provider wants real-time 

synchronization to be simulated; see GetStorelnfo. The 
ActiveSync service manager calls the 

IReplStore::IsFolderChanged method once the timer is up to see 
5 if it needs to scan the store ftirther to pick up any changes. This is 

used to reduce the number of scans replication has to make to the 
store. An ActiveSync service provider should return TRUE if it 
does not need to implement this method. 

1 0 See Also IReplStore::GetStoreInfo, STOREINFO 



]ReplStore::JsJtemChanged 

1 5 The IReplStore::IsItemChanged method determines if the object 

has changed. 

Syntax BOOL IsItemChanged( 

HREPLFLD hFolder, 
20 HREPLITEM hltem, 

HREPLITEM hltemComp 

:, - - ); • ... 

At a Glance Header file: Cesync.h 
25 Platforms: H/PC 

Windows CE versions: 2.0 and later 

Parameters hFolder 

Handle to the folder or container that stores the object. 

30 hltem 

Handle to the object. 
hltemComp 

Handle to the object used for comparison. 

35 Return Values FALSE 

The object has not been changed. 

TRUE 

The object has changed. 

40 Remarks If hltemComp is not NULL, the ActiveSync service provider 

should check the data (time stamp, change number) in hltem with 
hltemComp. If hltemComp is NULL, the ActiveSync service 
provider should get the data by opening the object and comparing 
it with the data in hltem. 

45 

See Also HREPLITEM, IReplStorerrCompareltem 
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JRepIStore::IsItemRepIicaled 



The IReplStore::IsItemReplicated method determines if an item 
should be replicated using ActiveSync service provider-defined 
rules. 



10 



15 



Syntax BOOL IsItemReplicated( 

HREPLIFLD hFolder, 
HREPL1TEM hltem 

); 

At a Glance Header file: 
Platforms: 

Windows CE versions: 



Cesync.h 
H/PC 

2.0 and later 



Parameters hFolder 



hltem 



20 



Return Values FALSE 



Handle to the folder or container that stores the object. 

Handle to the object. This parameter can be NULL, in 
which case, IsItemReplicated should determine if the 
specified folder should be replicated. 



25 



Remarks 



30 



35 See Also 



TRUE 



The object should not be replicated. 
The object should be replicated. 



If the ActiveSync service provider requires that some objects on 
the desktop computer should not be replicated, it can use the 
IReplStore::IsItemReplicated method to tell the ActiveSync 
service manager to ignore these objects. The ActiveSync service 
provider can design its own rules and store it using the handle of 
the folder. Jf all objects should be replicated, the ActiveSync 
service provider can return TRUE in all calls. 

IReplStore 



]Rep!Store::ObjectToBytes 



40 



45 



Syntax 



The IReplStore: :ObjectToBytes method converts the 
HREPLOBJ, which can be either a HREPLITEM or HREPLFLD, 
to an array of bytes when saving. 

UINT ObjectToBytes( 
HREPLOBJ hObject, 
LPBYTE Ipb 

); 
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At a Glance Header file: Cesync.h 

Platforms: H/PC 

Windows CE versions: 2.0 and later 

5 Parameters hObject 

Handle to an object. 

Ipb 

Handle to a buffer where the array of bytes should be 
stored. This parameter can be NULL. 



10 



Return Values Number of bytes in the array. 



Remarks The IReplStore::ObjectToBytes method is used to save the data 

represented by a handle to disk. The ActiveSync service manager 
15 calls ObjectToBytes first with Ipb set to NULL. The ActiveSync 

service provider should then return the size required, followed by 
the ActiveSync service manager calling ObjectToBytes with a Ipb 
parameter pointing to a buffer large enough for the array. 

20 See Also IReplStore::BytesToObject 



]ReplSlore::]sValidObject 

25 The IReplStore:;isValidObjecl method rielcnniiies if ihc specified 

handles are valid. 

Syntax HRESULT IsValidObject( 

HREPLFLD hFolder, 
30 HREPLITEM hltem, 

UINT, uFlags 

); 

At a Glance Header file: Cesync.h 

35 Platforms: H/PC 

Windows CE versions: 2.0 and later 

Parameters hFolder 

Handle to a folder. This parameter can be NULL. 

40 hltem 

Handle to an item. This parameter can be NULL. 

uFlags 

Reserved. Must be 0. 

45 Return Values NOERROR 

The specified handles are all valid. 
RERR_CORRUPT 

The data in the specified handle is corrupted. 
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RERR_OBJECT_DELETED 

The object identified by the handle is no longer in the 



store. 



5 Remarks The IReplStore::IsValidObject method is used to determine if the 
specified handles are valid. The ActiveSync service provider 
should check both hFolder and hhem to determine if either of 
them is not NULL. ! 

10 See Also IReplStore 



IRepIStore::RemoveDuplicates 

15 The IReplStore::RemoveDuplicates method finds and removes 

duplicated objects from the store. 

Syntax HRESULT Remove Duplicates( 

LPSTR IpszObjType, 
20 UINT uFlags 

); 



Header file: CesyncJ* 
Platforms: H/PC 
Windows CE versions: 2.0 and later . 

IpszObjType 

Pointer to the name of the object type for which this 
operation is intended. This parameter is NULL if all 
object types should be checked. 

uFlags 

Reserved. Always 0. 

Return Values NOERROR 
35 The operation completed successfully and there is no need 

to restart replication to pick up the deletions. 
R£RR_RESTART 

The operation completed successfully and replication 
should be restarted to pick up the deletions. 
40 E_NOTIMPL 

The ActiveSync service provider does not support this 
operation. 



At a Glance 

25 

Parameters 

30 
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Remarks Occasionally, the ActiveSync service manager might need to 

prompt an ActiveSync service provider to scan all objects in the 
store to check for duplicates and give the user a chance to remove 
them. The ActiveSync service provider should return 
E_NOTJMPL if it chooses not to implement this functionality. 
Otherwise, the ActiveSync service provider should perform the 
check and remove and return NOERROR or RERR_RESTAKT if 
successful. In this case, replication does not call the 
!ReplStore::RemoveDuplicates method again until necessary. It 
should return all other error values if, for some reason, operation 
cannot be performed at that time. In this case, replication calls 
RemoveDuplicates again at the end of the next synchronization. 

See Also IReplStore 



20 



25 



!ReplStore::ReportStatus 

ActiveSync service manager calls the IReplStore: :ReportStatus 
method to get information on the synchronization status. 

Syntax HRESULT ReponStatus( 

- liREPLTLD'-'h Folder 9 
HREPLITEM hltem, 
UINT uStatus, - . :. 
UINT uParam 

); 



At a Glance 



30 



35 



40 



45 



Header file: 
Platforms: 

Windows CE versions: 



Cesync.h 
H/PC 

2.0 and later 



Parameters hFolder 



hltem 



uStatus 



Handle to the folder this status applies to. This parameter 
is NULL if status applies to all folders. 

Handle to the object this status applies to. This parameter 
is NULL if status applies to all objects. 

Status code. Possible values include the following: 

RSC_BEGIN_SYNC 

Synchronization is about to start; uReservedh a 
combination of the following bit flags: 
BSF_AUTO_SYNC 

Synchronization is started as a result of changes 
while "autosvnc on change" is turned on. 
BSFJRJEM OTE_S YNC 
Consistent with RSCJREMOTE_SYNC, set if 
synchronization is done remotely. 
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RSC_END_SYNC 

Synchronization has ended. 
RSC_BEGIN_CHECK 

The ActiveSync service manager is about to call 

FindFirstltem and FindNextltem. 
RSC_END_CHECK i 

The ActiveSync service manager has completed all 

enumeration calls and FindltemClose has been 

called. 

RSCJ)ATE_CHANGED 

The user has changed the system date. This code 
is called on every existing object in the store to 
give the ActiveSync service provider a chance to 
reset the date-dependent synchronization options. 
For example, if an ActiveSync service provider 
wants to synchronize files that are modified in the 
last two weeks, it can respond to this code to reset 
the enable bit for each item. When 
IsItemReplicated is called later, it re-evaluates the 
items based on the new date. 
RSC_RELEASE 

The ActiveSync serv ice manager is about to ." 

release the IReplStore object. This is called before' 

the final IReplStore: .-Release caJJ. 
RSC_REMOTE_SYNC 

U uParam is TRUE, the ActiveSync service 

manager is about to start remote synchronization. 

The ActiveSync service provider should not show 

any Ul that requires user interaction from now on 

until this status code is used again with uParam 

equal to FALSE. 
RSCJNTERRUPT 

ActiveSync service manager is about to interrupt 

the current operation. 

The following values of uParam are defined only 
for RSCJNTERRUPT: 

PSA_RESET_INTERRUPT 

This flag is set if the interrupt state is being 

cleared; that is, normal operation is resuming. 

PSA_SYS_SHUTDOWN 
User has shut down the Windows operating 
system. 
RSC_BEGIN_SYNC_OBJ 

Synchronization is about to start on an object type. 
uReserved is a combination of bit flags; see 
RSC_BEGIN_SYNC. 
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RSC_END_SYNC_OBJ 

Synchronization is about to end on an object type. 
RSC_OBJ_TYPE_ENABLED 

Synchronization of the specified object is enabled; 
5 hFolder is a pointer to a string (object type name). 

RSC_OBJ_TYPE_D]SABLED ~ i 

Synchronization of the specified object is disabled; 

hFolder is a pointer to a string (object type name). 
RSCJ3EGIN_BATCH_WRITE 
10. A series of SetPackets is called on a number of 

objects. This is the time for ActiveSync service 

provider to start a transaction. 
RSC_END_BATCH_ WRITE 

RSCJ3EGIN~ BATCH_WRITE has ended. This 
15 is the time for the ActiveSync service provider to 

commit the transaction. 

rscj:onnection_chg 

The connection status has changed. uParam is 
TRUE if a connection has been established; 
20 otherwise, it is FALSE. 

RSC_WRITE_0BJ_FA1LED 

■ -There was a failure ^vhile wnting to £n objector 
the device. uPoram is the KRESULT code. 
RSC_DELETE_OBJ_F AILED 
25 There was a faiiure while deleting an object on the 

device. uParam is the HRESULT code. 

uParam 

Additional information about the status, based on uStatus 
code. 

) 

Return Values NOERROR 

The process indicated by uStatus is successful. 
E_FAIL 

The process indicated by uStatus has failed or encountered 
problems. 

Remarks The Active Sync service provider can return NOERROR for all 
cases if it is not interested. 

This is an application programming interface (API) exported by 
the Store.dll for the synchronization engine. 

See Also IReplStore 
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JReplStore::UpdateItem 

The IReplStore::UpdateItem method updates the object's time 
stamp, change number, and other information that is stored in the 
specified handle. 

void Updateltem( 
HREPLFLD hFolder, 
HREPLITEM hhemDsU 
HREPLITEM hhemSrc 

); 

Header file: Cesync.h 

Platforms: H/PC 

Windows CE versions: 2.0 and later 

hFolder 

Handle to a folder that stores the item. 
hhemDst 

Handle to the destination item. 
hhemSrc 

----- ; - i--- : . - .Handle tp,the soiVT^^tejn; could ba\Nl£LL."" : ' 
Return Values None. 

Remarks The ActiveSync service manager calls the 

IReplStore::UpdateItem method to update the relevant 
information, such as time stamp or change number, in the 
specified handle. If a source handle is specified, the ActiveSync 
30 service provider should copy the information over; otherwise, the 

ActiveSync service provider should open the object, then get the 
object's information and store it in the destination handle. 

See Also IReplStore 

35 

lEnumRepUtem 

The IEnumReplItem interface enables enumeration of a collection 
40 of items. 

Cesync.h 
H/PC 

2.0 and later 
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Syntax 
10 / 
At a Glance 

15 

Parameters 

20 



At a Glance Header file: 
Platforms: 

Windows CE versions: 
45 



WO 99/49394 
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Method 



Description 



lEnumReplItem::Clone 

IEnumR ep litem: :GetFolder 
Handle 

IEnumReplItem::Next 



JEnumReplltem::Reset 
IEnumReplItem::Skip 



Creates a copy of the current 
state of enumeration. 
Gets a handle to the folder 
(HREPLFD) that is currently 
being enumerated. 
Attempts to advance to the 
next item in the enumeration 
sequence. 

Resets the enumeration 
sequence to the beginning. 
Attempts to skip over the next 
item in the enumeration 
sequence. 



IEnumReplItem::CIone 

The IEnumR epl]tem::Clone method creates a copy of the current 
state of enumeration. 

HRESULT Go;ne( 

lEnumReplItem FAR * FAR * ppEnum, 

); 

Header file: Cesynch 

Platforms: H/PC 

Windows CE versions: 2.0 and later 

ppEnum 

Pointer to the place to return the cloned enumerator. The 
type oippEnum is the same as the enumerator name. For 
example, if the enumerator name is IEnumFORMTETC, 
20 ppEnum is of type lEnumFORMATETC. 

Return Values E JDUTOFMEMORY 
Out of memory. 
EJNVALIDARG 
25 Value oippEnum is invalid. 

EJJNEXPECTED 

An unexpected error occurred. 



Syntax 

10 

At a Glance 



15 

Parameters 



30 IEnumRep)Item::GetFolderHand)e 



The IEnumReplItem::GetFolderHandle method gets a handle to 
the folder (HREPLFLD) that is currently being enumerated. 
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Syntax 



hHREPLFLD GetFolderHandle (); 



At a Glance Header file: Cesynch 
Platforms: H/PC 
5 Windows CE versions: 2.0 and later 

Return Values Returns the handle to the folder (HREPLFLD) that is being 
enumerated. 



10 



IEnumReplltem::Next 



15 



20 



25 



Svntax 



At a Glance 



The IEnumReplItem::Next method attempts to advance to the 
next item in the enumeration sequence. 

HRESULT Next( 
unsigned long celt, 
HREPL1TEM *phhem, 
unsigned long FAR ^pCeltFetched, 

); 

Keader.iile: ... 
Piatforms: 

Windows CE versions: 



Cesynch 
H/PC 

2.0 and later 



Parameters celt 



30 



35 



40 



45 



Specifies the number of elements to return. If the number 
of elements requested is more than remains in the 
sequence, only the remaining elements are returned. The 
number of elements returned is passed through the 
pCeltFetched parameter, unless it is NULL. 

phhem 

Pointer to the structure in which to return the elements. 
pCeltFetched 

Pointer to the number of elements actually returned in 
* * phhem. The pCeltFetched parameter cannot be NULL if 
celt is greater than one. Likewise, if pCeltFetched is 
NULL, celt must be one. 

Return Values S_OK 

Returned the requested number of elements; phltem is set 
ifnon-NULL. All requested entries are valid. 
S_FALSE 

Returned fewer elements than requested in celt. In this 
case, unused slots in the enumeration are not set to NULL 
and * phhem holds the number of valid entries, even if 
zero is returned. 
E_OUTOFMEMORY 
Out of memory. 
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EJNVALIDARG 

The value of celt is invalid. 
EJJNEXPECTED 

An unexpected error occurred. 



IEnumRep]Item::Reset I 

The IEnuniReplItem::Reset method resets the enumeration 
10 sequence to the beginning. 

Syntax HRESULT Reset(): 

At a Glance Header file: Cesync.h 
15 Platforms: H/PC 

Windows CE versions: 2.0 and later 

Return Values S_OK 

The enumeration sequence was reset to the beeinning. 
20 S_FALSE 

The enumeration sequence was not reset to the beginning. 



25 



IEDumRep]]tem::Skip 



The IEnumReplltem::Skip method attempts to skip over the next 
item in the enumeration sequence. 



Syntax HRESULT Skip( 

30 unsigned lone celt, 

); 

At a Glance Header file: Cesync.h 

Platforms: H/PC 

35 Windows CE versions: 2.0 and later 

Parameters celt 

Specifies the number of elements to be skipped. 

40 Return Values S_OK 

The number of elements skipped is equal to celt. 
S_FALSE 

The number of elements skipped is fewer than celt. 
SJDUTOFMEMORY 
45 Out of memory. 

EJNVALIDARG 

The value of celt is invalid. 
EJJNEXPECTED 

An unexpected error occurred. 
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Chapter 19 

Fsdbase Component: Functions 
CeCreateDatabase 



10 



Syntax 



The CeCreateDatabase function creates a new database. A rJaPI 
version of this function exists and is also called 
CeCreateDatabase. 

CEOID CeCreateDatabase(LPWSTR IpszName, DWORD 
dwDbaseType, WORD wNumSortOrder, SORTORDERSPEC 
*rgSortSpecs); 



15 



At a Glance Header file: 
Component: 



Platforms: 

Windows CE versions: 



Winbase.h 

fsdbase 

H/PC 

1.01 and later 



20 Parameters 



25 



30 



35 



40 



Remarks 



45 



IpszName 

Pointer to a null-terminated string that specifies the name 
for the new database. The name ca» have up to 32 
characters, including the terminating null character. If th<? 
name is too long, it is truncated. 

dwDbaseType 

Type identifier for the database. This is an application- 
defined value that can be used for any application-defined 
purpose. For example, an application can use the type 
identifier to distinguish address book data from to-do list 
data or use the identifier during a database enumeration 
sequence. See CeFindFirstDatabase for details. The type 
identifier is not meant to be a unique identifier for the 
database. The system does not use this value. 

wNuniSortOrder 

Number of sort orders active in the database, with four 
being the maximum number. This parameter can be zero 
if no sort orders are active. 

rgSortSpecs 

Pointer to an array of actual sort order descriptions. The 
size of the array is specified by wNumSoriOrder. This 
parameter can be NULL if wNumSortOrder is zero. 

Because sort orders increase the system resources needed to 
perform each insert and delete operation, keep the number of sort 
orders to a minimum. However, try not to specify too few sort 
orders. If you do, you can use the CeSelDatabaselnfo function to 
change the sort order later; however, this function is even more 
expensive in terms of system resources. 
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Return Values If the function succeeds, the return value is the object identifier of 
the newly created database - not a handle to an open database. If 
the function fails, the return value is NULL. To get extended 
error information when within a CE program, call GetLastError. 
5 If within a RAPI program, call CeGetLastError. GetLastError 

and CeGetLastError may return one of the following values: 

ERROR JMSKFULL 

The object store does not contain enough space to create 
10 the new database. 

ERROR JNVALIDJ>ARAMETER 
A parameter was invalid. 

15 ERROR_DUP_NAME 

A database already exists with the specified name. 

For more information, see Accessing Persistent Storage. 

20 When writing applications for Windows CE version 1 .0, use the 

PegCreateDatabase function. 

. See Also. CeDeleteDatabase, CeOidGetlnfo, CeOpenDatabase, 
CeSetDatabaselnfo, SORTORDERSPEC 

25 

CeDeleteDatabase 

The CeDeleteDatabase function removes a database from the 
30 object store. A RAPI version of this function exists and is also 

called CeDeleteDatabase. 

Syntax BOOL CeDeleteDatabase(CEOID oidDbase); 

35 At a Glance Header file: Winbase.h 

Component: fsdbase 

Platforms: H/PC 

Windows CE versions: 1.01 and later 

40 Parameters oidDbase 

Object identifier of the database to be deleted. 

Return Values ]f the function succeeds, the return value is TRUE. If the function 
fails, the return value is FALSE. To get extended error 
45 information when within a CE program call GetLastError. If 

within a RAPI program, call CeGetLastError. GetLastError and 
CeGetLastError may return one of the following values: 
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ERROR_INVALID_PARAMETER 
A parameter was invalid. 

ERROR_SHARING_VIOLATION 
5 Another thread has an open handle to the database. 

Remarks The CeDeleteDatabase function deletes a database, including jail 
records in the database. 

1 0 For more information, see Accessing Persistent Storage. 

When writing applications for Windows CE version 1 .0, use the 
PegDeleteDatabase function. 

15 See Also CeCreateDatabase, CeOidGetlnfo 



20 



CeDeleteRecord 



The CeDeleteRecord function deletes a record from a database. A 
. RAPI version of .this function exists and is also called 

CeDeleteRecord. 

25 Syntax BOOL CeDeleteRecord(HANDLE hDatabase, CEOID 

oidRecord); 

At a Glance Header file: Winbasch 
Component: fsdbase 
30 Platforms: H/PC 

Windows CE versions: 1 .01 and later 

Parameters hDatabase 

Handle to the database from which the record is to be 
35 deleted. The database must be open. Open a database by 

calling the CeOpenDatabase function. 
oidRecord 

Object identifier of the record to be deleted; this is 
obtained from CeOpenDatabase. 

40 

Return Values If the function succeeds, the return value is TRUE. If the function 
fails, the return value is FALSE. To get extended error 
information when within a CE program cell GetLastError. If 
within a RAPI program, call CeGetLastError. GetLastError and 
45 CeGetLastError may return ERROR JNVALID_PARAJV1ETER 

if the handle or object identifier is invalid. 
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Remarks If the CEDB_AUTOINCREMENT flag was not specified when 
the database was opened, and the record being deleted is the 
current record, the next read operation that uses the database 
handle will fail. If the CEDB_AUTOINCREMENT flag was 
5 specified, the system automatically moves the cuirent seek 

pointer forward by one. 

When writing applications for Windows CE version 1 .0, use the 
PegDeleteRecord function. 

10 

See Also CeOpenDatabase 



1 5 CeFindFirstDatabase 

The CeFindFirstDatabase function opens an enumeration context 
for all databases in the system. A RAPI version of this function 
exists and is also called CeFindFirstDatabase. 

20 

Syntax HANDLE CeFindFirstDatabase(DWORD dwDbaseType); 

At a Glance Header file: Winbass.h 1 11 

Component: fsdbase 

Platforms: H/PC 
25 Windows CE versions: 1.01 and later 

Parameters dwDbaseType 

Type identifier of the databases to enumerate. If this 
parameter is zero, all databases are enumerated. 

30 

Return Values If the function succeeds, the return value is a handle to an 

enumeration context. To find the next database of the given type, 
specify the handle in a call to the CeFindNextDatabase function. 
If the function fails, the return value is 
35 INVALID_HANDLE_VALUE. To get extended error 

information when within a CE program call GetLastError. If 
within a RAPI program, call CeGetLastError. GetLastError and 
CeGetLastError may return ERROR J3UTOFMEMORY if no 
memory is available to allocate a database handle. 

40 

Remarks Use the CeCloseHandle function to close the handle returned by 
the CeFindFirstDatabase function. 



45 



For more information, see Accessing Persistent Storage. 

When writing applications for Windows CE version 1 .0, use the 
PegFindFirstDatabase function. 

See Also CeFindNextDatabase, CeCloseHandle 
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CeFindNextDatabase 

The CeFindNextDatabase function retrieves the next database in 
an enumeration context. A RAP1 version of this function exists 
5 and is also called CeFindNextDatabase. 

Syntax CEOID CeFindNextDatabase(HANDLE hEnum); 

At a Glance Header file: Winbase.h 

10 Component: fsdbase 

Platforms: H/PC 

Windows CE versions: 1 .01 and later 

Parameters hEnum 
15 Handle to an enumeration context; this handle is returned 

from CeFindFirslDatabase. 

Return Values If the function succeeds, the return value is the object identifier of 
the next database to be enumerated. If no more databases are left 
20 to enumerate, or if an error occurs, the return value is zero. To 

get extended error information when within a CE program, call 
GetLastError. If within a RAPlprojpam, call CeGciT;a^.Error 
GetLastError and CeGetLasiliiTcr may return one of the 
following values: 



ERROR_NO_MOREJTEMS 

The object store contains no more databases to enumerate. 



ERROR JNVALIDJ>ARAMETER 
30 The hEnum parameter specified an invalid handle. 

Remarks When writing applications for Windows CE version 1 .0, use the 
PegFindNextDatabase function. 

35 See Also CeFindFirstDatabase 



CeOpenDatabase 

40 The CeOpenDatabase function opens an existing database. A 

RAPI version of this function exists and is also called 
CeOpenDatabase. 

Syntax HANDLE CeOpenDatabase(PCEOID poid, LPWSTR IpszName, 

45 CEPROPID propid, DWORD dwFIags, HWND hwndNotify)\ 
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At a Glance Header file: Winbase.h 
Component: fsdbase 
Platfonns: H/PC 
Windows CE versions: 1 .01 and later 

5 

Parameters poid 

Pointer to the object identifier of the database to be 
opened. To open a database by name, set the value 
pointed to by poid to zero to receive the object identifier 
1 0 of the newly opened database when a database name is 

specified for IpszName. 
IpszName 

Pointer to the name of the database to be opened. This 
parameter is ignored if the value pointed to by poid is non- 
15 zero. 

propid 

Property identifier of the primary key for the sort order in 
which the database is to be traversed. All subsequent calls 
to CeSeekDatabase assume this sort order. This parameter 
20 can be zero if the sort order is not important. 

dwFlags 

c.;. Action fi ag.;. The folio wmg values are supported: ■ 

CEDB_AUTOINCREMENT 
25 Causes the current seek position to be 

automatically incremented with each call to the 
CeReadRecordProps function. 

0(ZERO) 

30 Current seek position is not incremented with each 

call to CeReadRecordProps. 

hwndNotify 

Handle to the window to which notification messages 
(DB_CEOID_*) will be posted if another thread modifies 
35 the given database while you have it open. This parameter 

can be NULL if you do not need to receive notifications. 

Return Values If the function succeeds, the return value is a handle to the open 
database. If the function fails, the return value is 
40 JNVALID_HANDLE_VALUE. To get extended error 

information when within a CE program cell GetLastEnror. If 
within a RAPI program, call CeGetLastError. GetLastError and 
CeGetLastError may return one of the following values: 

45 ERROR JNVALID_PARAMETER 

A parameter was invalid. 
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ERR OR_FILE_NOT_FOUND 

No database exists with the specified name. This value 
applies only if the value pointed to by poid was set to 
NULL when the function was called. 

5 

ERROR_NOTJENOUGH_MEMORY 

No memory was available to allocate a database handle. 

Remarks Use the CeCloseHandle function to close the handle returned by 
1 0 the CeOpenDatabase function. 

Unlike many other traditional databases, opening and closing a 
database does not imply any transactioning. In other wordsfthe 
database is not committed at the closing - it is committed after 
15 each individual call. 

For more information, see Accessing Persistent Storage. 

When writing applications for Windows CE version 1 .0, use the 
20 PegOpenDatabase function. 

. See Also .. .; .-^CeCloseHandle, CeCreateDatabase, CeSs£kDalab^~ 



25 CeReadRecordProps 

The CeReadRecordProps function reads properties from the 
current record. A RAPI version of this function exists and is also 
called CeReadRecordProps. 

Syntax CEOID CeReadRecordProps(HANDLE hDbase, DWORD 

dwFIags, LPWORD IpcPropID, CEPROPID *rgProplD, 
LPBYTE * IplpBuffer, LPDWORD IpcbBuffer); 

35 At a Glance Header file: Winbase.h 

Component: fsdbase 

Platforms: H/PC 

Windows CE versions: 1.01 and later 

40 Parameters hDbase 

Handle to an open database. The database must have been 
opened by a previous call to the CeOpenDatabase 
function. 

45 dwFlags 

Read flags. The following value is supported: 
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CEDB_ALLOWRE ALLOC 

The LocalAUoc function was used to allocate the 
buffer specified by the IplpBuffer parameter, and 
the server can reallocate the buffer if it is not large 
5 enough to hold the requested properties. 

IpcPropID 

Number of property identifiers in the array specified by 
the rgPropID parameter. If rgPropID is NULL, this 
10 parameter receives the number of properties retrieved. 

rgPropID 

Pointer to an array of property identifiers for the 
properties to be retrieved. If this parameter is NULL, 
CeReadRecordProps retrieves all properties in the record. 

15 IplpBuffer 

Address of a pointer to a buffer that receives the requested 
properties. If the dwflags parameter includes the 
CEDB_ALLOWRE ALLOC flag, the buffer may be 
reallocated if necessary. If the 

20 CEDB^ALLOWREALLOC flag is specified and this 

parameter is NULL, the server uses the LocalAUoc 
- - ; - functioiitb allocate a buffers 

caller's address space and letums a pointer to the buf&r 
Note that if the CEDB_ALLOWRE ALLOC flay, is 

25 specified, it is possible for the value of this pointer lo 

change even on failure. For example, the old memory 
might be freed and the allocation might then fail, leaving 
the pointer set to NULL. 
IpcbBuffer 

30 Pointer to a variable that contains the size, in bytes, of the 

buffer specified by the IplpBuffer parameter. When 
CeReadRecordProps returns, IpcbBuffer receives a value 
that indicates the actual size of the data copied to the 
buffer. If the buffer was too small to contain the data, this 

35 parameter can be used to calculate the amount of memory 

to allocate for the buffer if CEDB_ALLOWRE ALLOC 
was not specified. 

Return Values If the function succeeds, the return value is the object identifier of 
40 the record from which the function read. If the functional fails, 

the return value is zero. To get extended error information when 
within a CE program, call GetLastError. If within a RAP1 
program, call CeGetLastError. GetLastError and CeGetLastError 
may return one of the following values: 

45 

ERE OR_INV ALID_P ARAMETER 
A parameter was invalid. 
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ERRORNO_DATA 

None of the requested properties was found. The output 
buffer and the size are valid. 

ERROR JNSUFFICIENT_BUFFER 

The given buffer was not large enough, and the 
reallocation failed — if the CEDB_ALLOWREALLOC 
flag was specified. The IpcbBuffer parameter contains the 
required buffer size. 

ERROR_KEY_DELETED 

The record that was about to be read was deleted by 
another thread. If the current record was reached as a 
result of an autoseek, this error is not returned, and the 
next record is returned. 

ERROR_NO_MORE_ITEMS 

The current seek pointer is at the end of the database. 

The CeReadRecordProps function reads the specified set of 
properties from the current record. If the database was opened 
with .the autoseek flag--:-- that is, \f \tet&Fiags paraiieter cif ' 
CeOpenDatabase was sei to % CEDB_AUTOINCREMENl* — 
CeReadRecordProps increments the seek pointer by one so that 
the next call reads the next record in the current sort order. That 
is. if the database was opened with a sort order active, then 
CeReadRecordProps will return the records in sorted order. If the 
database was not opened with a sort order active, then the order in 
which records are returned is not predictable. 

Read all needed properties from the record in a single call. The 
entire record is stored in a compressed format, and each time a 
property is read it must be decompressed. All the properties are 
returned in a single marshaled structure, which consists of an 
array of CEPROPVAL structures, one for each property requested 
— or one for each property found if the application set the 
rgPropJD parameter to NULL when calling the function. 

If a property was requested, such as strings or blobs that are 
packed in at the end of the array, the pointers in the 
CEPROPVAL structures point intolhis marshaled structure. This 
means that the only memory that must be freed is the original • 
pointer to the buffer passed in to the call. Even if the function 
fails, it may have allocated memory on the caller's behalf. Free 
the pointer returned by this function if the pointer is not NULL. 

For more information, see Accessing Persistent Storage. 
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See Also 



When writing applications for Windows CE version 1 .0, use the 
PegReadRecordProps function. 

LocalAHoc, LocalFree, CeOpenDatabase, CeSeekDatabase, 
CEPROPVAL 



CeSeekDatabase 



10 



15 Syntax 



At a Glance 



20 



The CeSeekDatabase function seeks the specified record in an 
open database. A RATI version of this function exists and is also 
called CeSeekDatabase. 

CEOID CeSeekDatabase(HANDLE hDatabase, DWORD 
dwSeekType, DWORD dwValue, LPDWORD IpdwJndex); 



Header file: 
Component: 
Platforms: 

Windows CE versions: 



Winbase.h 

fsdbase 

H/PC 

1.01 and later 



25 



30 



35 



40 



45 



Parameters-/ : hDatabase' '■ - 

Handle to the open database in which to seek. 
dwSeekType 

Type of seek operation to perform. This parameter can be 
one of the following values: 

CEDB_SEEK_CEOID 

Seek until finding an object that has the given object 
identifier. The dwValue parameter specifies the object 
identifier. This type of seek operation is very 
efficient. 

CEDB_SEEK_VALUESMALLER 

Seek until finding the largest value that is smaller than 
the given value. If none of the records has a smaller 
value, the seek pointer is left at the end of the database 
and the function returns zero. The dwValue parameter 
is a pointer to a CEPROPVAL structure. 

C EDB_S EEK_ V ALUEFIRS TEQU AL 

Seek until finding the first value that is equal to the 
given value. If the seek operation fails, the seek 
pointer is left pointing at the end of the database, and 
the function returns zero. The dwValue parameter is a 
pointer to a CEPROPVAL structure. 
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CEDB_SEEKJVALUENEXTEQUAL 

Starting from the current seek position, seek exactly 
one position forward in the sorted order and check if 
the next record is equal in value to the given value. If 
so, return the object identifier of this next record; 
otherwise, return zero and leave the seek pointer at the 
end of the database. This operation can be used in 
conjunction with the 

CEDB_SEEKJVALUEFIRSTEQUAL operation to 
enumerate all records with an equal value. The 
dwValue parameter specifies the value for which to 
seek. 

CEDB_SEEK_VALUEGREATER 

Seek until finding a value greater than or equal to the 
given value. If all records are smaller, the seek pointer 
is left at the end of the database and the function 
returns zero. The dwValue parameter is a pointer to a 
CEPROPVAL structure. 

CEDB_SEEK_BEGINNING 
. Seek until finding the record at the g ; vsn position fircnj 
"the beginning of the database. The dwValue pa:amettr 
specifies the number of records to seek. 

CEDB_SEEK_CURRENT 

Seek backward or forward from the current position of 
the seek pointer for the given number of records. The 
dwValue parameter specifies the number of records 
from the current position. The function seeks forward 
if dwValue is a positive value, or backward if it is 
negative. A forward seek operation is efficient. 

CEDB_SEEK_END 

Seek backward for the given number of records from 
the end of the database. The dwValue parameter 
specifies the number of records. 

dwValue 

Value to use for the seek operation. The meaning of this 
parameter depends on the value of dwSeekType. 

Ipdwlndex 

Pointer to a variable that receives the index from the start 
of the database to the beginning of the record that was 
found. 



SUBSTITUTE SHEET (RULE 26) 



WO 99/49394 



PCTAJS99/06223 



80 

Return Values If the function succeeds, the return value is the object identifier of 
the record on which the seek ends. If the function fails, the return 
value is zero. To get extended error information when within a 
CE program call GetLastError. If within a RAPI program, call 
CeGetLastError, GetLastError and CeGetLastError may return 
ERROR JNVALID_PARAMETER if a parameter is invalid. 

Remarks The CeSeekDatabase function always uses the current sort order 
as specified in the call to the CeOpenDatabase function. If the 
CEDBAUTOINCREMENT flag was specified, an automatic 
seek of one from the current position is done with each read 
operation that occurs on the database. 

Note that a seek can only be performed on a sorted property 
value. After creating a database (using CeCreateDatabase) and 
opening the database (using CeOpenDatabase), subsequent calls 
to CeSeekDatabase assume the sort order that was specified in the 
propid parameter of the call to CeOpenDatabase. Although 
property identifiers can be modified using CeWriteRecordProps, 
it is best to use the same property identifier for CeOpenDatabase 
that was used for the propid member of the SORTORDERSPEC 
structure that was passed hi the ^;;11 to CeCrca^Datah&se. 

To enter negative values for the CEDB_SEEK_ CURRENT case, 
cast a signed long. This changes the effective range on the record 
indexes to 3 1 bits from 32. 

Multiple sort orders cannot be specified for a single property. 

For more information, see Accessing Persistent Storage. 

When writing applications for Windows CE version 1.0, use the 
PegSeekDatabase function. 

35 See Also CeCreateDatabase, CeOpenDatabase, CEPROPVAL 



15 



20 



CeSetDatabaselnfo 

40 

The CeSetDatabaselnfo function sets various database 
parameters, including the name, type, and sort-order descriptions. 
A RAPI version of this function exists and is also called 
CeSetDatabaselnfo. 

45 

Syntax BOOL CeSetDatabaseInfo(CEOID oidDbase, CEDBASEINFO 

*pNewInfo); 
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At a Glance Header File: Winbase.h 
Component: fsdbase 
Platforms: H/PC 
Windows CE versions: 1 .01 and later 

5 

Parameters oidDbase \ 

Object identifier of the database for which parameters are 
to be set. 
pNewInfo 

1 0 Pointer to a CEDBASEINFO structure that contains new 

parameter information for the database. The 
wNumRecords member of the structure is not used. 

Return Values If the function succeeds, the return value is TRUE. If the function 
1 5 fails, the return value is FALSE. To get extended error 

information when within a CE program call GetLastError. If 
within a RAPI program, call CeGetLaslError. GetLastError and 
CeGetLastError may return one of the following values: 

20 ERROR JNVALIDJPARAMETER 

A parameter was invalid. 

ERROR ^DiSK^FULL 

The object store is fail and any size changes required 
co\}\q not be accommodated. Changing sort orders can 
change the size of the stored records, though not by much. 

ERROR_SHARJNG_V!OLATION 

CeSetDatabaselnfo tried to remove a sort order that is 
30 being used by a currently open database. 

Remarks The CeSetDatabaselnfo function can be used to change the 

database parameters passed in while creating the database. Note 
that changing the sort order of the database can take several 
35 minutes. Before calling CeSetDatabaselnfo, an application 

should wam the user that this operation can be lengthy. 

For more information, see Accessing Persistent Storage. 

40 When writing applications for Windows CE version 1 .0, use the 

PegSetDatabaselnfo function. 

See Also CeCreateDatabase, CEDBASEINFO, CeOidGetlnfo 

45 
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CeWriteRecordProps 



Syntax 



10 At a Glance 



The CeWriteRecordProps function writes a set of properties to a 
single record, creating the record if necessary. A RAPI version of 
this function exists and is also called CeWriteRecordProps. 

CEOID CeWriteRecordProps(HANDLE hDbase, CEOID 
oidRecord, WORD cProplD, CEPROPVAL * rgPropVal); 



Header File: 
Component: 
Platforms: 

Windows CE versions: 



Winbasch 

fsdbase 

H/PC 

1.01 and later 



1 5 Parameters 



20 



25 



30 



35 



40 



45 



hDbase 

Handle to an open database. The database must have been 
opened by a previous call to the CeOpenDatabase 
function. 
oidRecord 

Object identifier of the record to which the given 
properties are to be written. If this parameter is zero, a 
new record is created and filled in with ihe given - 
properties. 
cPropID 

Number of properties in the array specified by the 
rgPropVal parameter. The cPropID parameter must not 
be zero. 
rgPropVal 

Pointer to an array of CEPROPVAL structures that 
specify the property values to be written to the given 
record. 



Return Values If the function succeeds, the return value is the object identifier of 
the record to which the properties were written. If the function 
fails, the return value is zero. To get extended error information 
when within a CE program call GetLastError. If within a RAPI 
program, call CeGetLastError. GetLastError and CeGetLastError 
may return one of the following values:: 

ERROR_DJSK_FULL 

There was not enough space in the object store to write the 
properties. 

ERROR JNVALID_PARAMETER 
A parameter was invalid. 

Remarks The CeWriteRecordProps function writes all the requested 

properties into the specified record. CeWriteRecordProps does 
not move the seek pointer. 
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To delete a property, set the CEDB_PR OPDELETE flag in the 
appropriate property value. This allows multiple deletes and 
changes in a single call, which is much more efficient than 
5 multiple calls. 

No memory is freed by the callee. Pointers in the CEPROpIaL 
structures can be anywhere in the caller's address space— they can 
be marshaled in like the array returned by CeReadRecordProps, 
0 or they can be independently allocated. 

For more information, see Accessing Persistent Storage. 

When writing applications for Windows CE version 1 .0, use the 
> PegWriteRecordProps function. 
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Detailed Description of Data Structures for a Database API 
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CHAPTER 95 

Fsdbase Component: Structures 



CEDBASEINFO 

The CEDBASEINFO structure contains information about a 
database object. This structure is used by the CeSetDatabaselnfo 
10 and CeCreateDatabaseEx functions. 

Syntax typedef struct_CEDB ASEINFO { 

DWORD dwFlags 

WCHAR szDbaseName 
15 [CEDB_MAXDBASENAMELEN]; 

DWORD dwDbaseType; 

WORD wNumRecords; 

WORD wNumSortOrder; 

DWORD dwSize; 
20 FILETIME ftLastModified; 

SORTORDERSPEC 

rgSortSpecs[CED3 MAXSORTORDFF1; 
} CEDBASEINFO 

25 At a Glance Header file: WindbaseJi 
Platforms: H/PC 
Versions: 1.01 and later 

Members dwFlags 

30 ^ LOWORD indicates the valid members of this 

structure. This member can be a combination of the 
following values: 

CEDBlVALIDMODTlME 
35 The ftLastModified member is valid and should be 

used. 

CEDB_VALIDNAME 

The szDbaseName member is valid and should be 
40 used. 

CEDB_VALIDTYPE 

The dwDbaseType member is valid and should be 
used. 



45 



CEDB_ VALID SORTSPEC 

The rgSortSpecs member is valid and should be 
used. 
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CEDB_VALIDDBFLAGS 

The LOWORD of dwFlags member is valid and 
should be used. 

The HIGH WORD identifies the associated database 
properties. This member can be a combination of the 
following values: 

CEDB_NOCOMPRESS 

The database is not compressed. If this flag is 
used with CeSetDatabaselnfoEx, a compressed 
database is uncompressed. If this flag is used with 

CeCreateDatabaseEx, the database is not 
compressed. 

To compress a database, CeSetDatabaselnfoEx or 
CeCreateDatabaseEx is called with 
CEDB_VALIDDBFLAGS and the HIGHWORD 
set to zero. By default, all databases are 
compressed. If you are going to change the 
compression, it should be done at creation time. 

szDbaseName 

Null-terminated string that contains the name of the 
database. The string can have up to 32 characters, 
including the termination null character. This member 
must be set when used for CeCreateDatabaseEx. 

dwDbaseType 

Type identifier for the database. 

wNumRecords 

Returns the number of records in the database. 

wNumSonOrder 

Number of sort orders active in the database. Up to four 
sort orders can be active at a time. 

dwSize 

Returns the size, in bytes, of the database. 
fiLastModified 

Returns the last time this database was modified. 
rgSortSpecs 

Array containing the sort order descriptions. Only the first 
n array members are valid, where n is the value specified 
by the wNumSort Order member. If no sort orders are 
specified for CeCreateDatabaseEx or when 
CEDB_VAL1DS0RTSPEC is not specified, th£n a default 
sort order is assigned to the database. 

CeCreateDatabaseEx, CEOIDINFO, CeSetDatabaselnfoEx 
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CEOID1NFO 

The CEOIDINFO structure contains information about an object 
in the object store. 

5 

Syntax typedef struct_CEOIDINFO { 

WORD wObjType; 
DWORD dwSize; 
WORD wPad; 
10 union { 

CEFILEINFO infFile; 
CEDIRINFO infDirectory; 
CEDBASEINFO infDatabase; 
CERECORDINFO infRecord; 

15 }; 

} CEOIDINFO; 

At a Glance Header file: Windbasch 
Platforms: H/PC 
20 Versions: 1.01 and later 

Members wObjType 

Type of the object. This member can bi- one ot the 
following values: 



25 



35 



OBJTYPEJNVALID 

The object store contains no valid object that has 
this object identifier. 



30 OBITYPE_FILE 

The object is a file. 



OBJTYPE_DIRECTORY 

The object is a directory. 

OBJTYPE_DATABASE 

The object is a database. 



OBJTYPE_RECORD 
40 The object is a record inside a database. 

dwSize 

Must be set to the size of CEOIDINFOEX, that is, 
size(CEOIDINFOEX). 

45 wPad 

Aligns the structure on a double-word boundary. 
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10 



15 



See Also 



infFile 

A CEFILEINFO structure that contains information about 
a file. This member is valid only if wObjType is 
OBJTYPE_FILE. 
infDirectory 

A CEDIRINFO structure that contains information about a 
directory. This member is valid only if wObjType is j 
OBJTYPE_DIRECTORY. 
infDatabase 

A CEDBASEINFO structure that contains information 
about a database. This member is valid only if wObjType 
is OBJTYPE_DATABASE. 
infRecord 

A CERECORDINFO structure that contains information 
about a record in a database. This member is valid only if 
wObjType is OBJTYPE_RECORD. 

CEDBASEINFO, CEDIRINFO, CEFILEINFO, 
CERECORDINFO 



20 



CEPROPVAL - 
25 The CEPROPVAL structure contains a property value. 

Syntax typedef struct_CEPROPVAL { 

CEPROPID propid; 
WORD wLenData; 
30 WORD wFlags; 

CEVALUN10N val; 
} CEPROPVAL; 

typedef CEPROPVAL *PCEPROPVAL; 



35 At a Glance Header file: 
Platforms: 
Versions: 



Windbase.h 
H/PC 

1.01 and later 



Members 



40 



45 



propid 



Identifier of the property value. The high-order word is an 
application-defined identifier, and the low-order word is a 
predefined constant value that indicates the data type of 
the value specified by the val member. The low-order 
word can be one of the following values: 

CEVT_BLOB 

A CEBLOB structure. 
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CEVT_FILENAME 

A FILENAME structure. 

CEVTJ2 

5 A 1 6-bit signed integer. 

CEVr 14 

A 32-bit signed integer. 

10 CEVT_LPWSTR 

A null-terminated string. 



15 



CEVTUI2 

A 1 6-bit unsigned integer. 

CEVTUI4 

A 32-bit unsigned integer. 



wLenData 
20 Not used. 

wFlags 

Special flags for the property. This parameter can be one 
of the following values: 

25 CEDB_PROPN07FOUND 

Set by the CeReadRecordProps function if the 
property was not found. 

CEDB_PROPDELETE 
30 If passed to the CeWriteRecordProps function, this 

flag causes the property to be deleted. 

val 

Actual value for simple types, or a pointer for strings or 
35 Binary Large Objects (BLOBs). 

Remarks When writing applications for Windows CE version 1 .0, use the 
PEGPROPVAL structure. 

40 See Also CeReadRecordProps, CeSeekDatabase, CeWriteRecordProps 



SORTORDERSPEC 

45 

The SORTORDERSPEC structure contains information about a 
sort order in a database. 
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15 



20 



25 



30 



Syntax typedef struct_SORTORDERSPEC { 

propid; 
dwFlags; 



PEGPROPID 
DWORD 
} SORTORDERSPEC; 



35 



At a Glance Header file: 
Platforms: 



10 Members 



Remarks 
See Also 



Versions: 
propid 



Windbase.h 
H/PC 

1.0 and later 



Specifies the identifier of the property to be sorted on. 
Sorts on binary properties are not allowed. 
dwFlags 

Specifies the sort flags. This parameter can be a 
combination of the following values: 

CEDB_S ORT_DES CENDING 

The sort is done in descending order. By default, 
the sort is done in ascending order. 

CEDB_SORT_CASEINSENSITIVE 

The sort operation is case sensitive. This v >!ue is 
valid only for strings. 

CEDB_SORT_UNKOWNFIRST 

Records that do not contain this property are 
placed before all the other records. By default, 
such records are placed after all other records. 

CEDB_SORT GENERJCORDER 

The system supports only simple sorts on a primary key. Records 
with the same key value are sorted in arbitrary order. 

CeCreateDatabase, CeDBASEINFO 
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IPosNav 



10 



15 



20 



25 



30 



35 



The IPosNav interface provides all the methods needed to utilize Apollo's 
GPS capabilities. 



Method 



IPosNav: :CloseHandle 
IPosNav::pnapiDeleteDeviceList 

IPosNav: rpnapiFindDevices 

IPosNav: :pnapiGetData 

IPosNav::pnapiOpenDevice 

IPosNav::pnapiSetData 

IPosNav: :pnapiStartDirectCall 

IPosNav: :pnapiStopDirectCall 

IPosNav::pncnvBearingToVelocity 
IPosNav::pncnvDegreesToRadians 
IPosNav: :pncnvPNTMTo Wintm 



Description 



Closes a P&N device 
Deletes a linked list of PNDEVICE 
structures 

Finds all connected P&N devices 
on the system 

Retrieves various types of data from 
a P&N device 
Opens a P&N device for 
communication 
Sends data to either the P&N 
device, or the registry 
Starts a call to get data from the 
P&Ndevice 
Stops a 

IPosNav::pnapiStartDirectCall that 
has been j^rted 

Con verts a bearing and two speeds 
to East, North and Up velocities 
Converts latitude/lcngitude/anhude 
data from degrees to radians 
Converts time, in PNTM format, to 
Win32 SYSTEMTIME format 
IPosNav: :pncnvRandiansToDegrees Converts latitude/longitude/altitude 

data from degrees to radians 



IPosNav::pncnvVelocityToBearing 
IPosNav: :pncnv WintmToPNTM 



Converts North/East/Up velocity 
data to a bearing and two speeds 
Converts time in Win32 format to 
PNTM fonnat 



40 



45 



Remarks The Position and Navigation API (PNAPI) for the AutoPC is a 
subset of the full PNAPI. The IPosNav interface handles most 
GPS-related tasks. The other interface, IDGPS, contains a small 
set of methods that are needed to support differential GPS. 

]PosNav::CloseHandle 

The IPosNav::CloseHandle method is used to close a P&N 
device. 

Syntax HRESULT CloseHandle ( 

hPNDevice hPN, 

); 
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Parameters hPN 



Handle to the P&N device to be closed. 



10 



15 



20 



Return Values S_OK 

Function succeeded. 
E_FAIL 

Unspecified error. 
E_INVALIDARG 

One or more arguments are invalid. 
EJsIOTIMPL 

Not implemented. 
PNAPI_E_DEV1CEUNAVA1LABLE 

P&N device not available (Unplugged? Dead?). 
PN API_E_M EMFREE 

Memory/resource cannot be freed. 



Example 
Remarks 



XX 



If this method is not called upon exiting, PNAPI resources will 
not be deleted. 



25 



This method must wait for pending calls to finish before stopping 
calls to a P&N device. It may therefore take a second or two to 
return. 



30 



See Also IPosNav::pnapiOpenDevice 



IPosNav::pnapiDeleteDeviceList 



35 



The IPosNav::pnapiDeleteDeviceList method is used to delete a 
linked list of PNDEV1CE structures 

Syntax HRESULT pnapiDeleteDeviceList ( 

pPNDEVICE pPNDeviceHead 

); 



40 Parameters pPNDeviceHead 

Pointer to the first structure in the linked list. 



45 



Return Values S OK 



Errors 



Successful. 

Returns the appropriate HRESULT error value. 



Remarks After opening the selected P&N device(s), delete the PNDEVICE 
linked list by using the pnapiDeleteDeviceList function. 
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See Also IPosNav::pnapiFindDevices 

5 ]PosNav::pnapiFindDevices 

The IPosNav::pnapiFindDevices method is used to find all 
connected pointing and navigation devices on the system. 

1 0 Syntax HRESULT pnapiFindDevices ( 

ppPNDEVICE ppDevArray 
DWORD *pdwNumDev 

); 

pDevArray 

Pointer to an array of PNDEVICE pointers. Returns the 
head of a linked list of PNDEVICE structures. The user 
should destroy this list with the pnapiDeleteDeviceList 
function. 
pdwNumDev 

Returns the number of P&N devices found. 

Values S_OK 

Function succeeded. 
E_FAIL 

Unspecified error. 
EJNVALIDARG 

One or more arguments are invalid. 
E_NOTIMPL 

Not implemented. 
TYPE_E_DLLFUNCTI ONNOTFOUND 

Function not defined in specified DLL. 
REGDB_E_READREGDB 

Could not read key from registry. 
PNAPI_E_INVALIDREGDB VALUE 

Invalid value in registry. 
PNAPI_E_REGDBCLOSEKEY 
Can't close a registry key. 
PNAPI_E_MEMFREE 

Memory/resource cannot be freed. 
PNAPI_E_BADOS 

Invalid operating system version. 
E_OUTOFM EM OR Y 

PNAPI has run out of memory. 
45 

Remarks The IPosNav::pnapiFindDevices method returns information for 
P&N devices in an 'unknown' status, but does not return data on a 
truly 'dead' P&N device. 
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20 



Return 

25 



30 



35 
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See Also EPosNav::pnapiOpenDevice, IPosNav::pnapiDeleteDeviceList 



5 IPosNav::pnapiGetDala 

The IPosNav::pnapiGetData method is used to get various 
of data from a P&N device. 

10 Syntax HRESULT pnapiGetData ( 

hPNDevice hPN, 
LPVOID pBuffer, 
DWORD dwSize, 
PNDataJ DataType 

15 ); 



tyj>es 



Parameters hPN 



20 



25 



Data Type 



P&N handle for the P&N device to use. 

pBuffer 

Pointer to the buffer that will receive the data. If any part 
of the requested data cannot be found, the corresponding 
entry in the PNAV strucrur^ that will be oar: of the buiftj 
is marked as invalid. 

dwSize 

Size of pBujfcr. 
DataType 

Type of data to get from the P&N device. The following 
types of data can be requested. 



Description 


Structure Type 


Long,lat,alt position data 


PNPOSITION 


Velocity data 


PNVELOCITY 


Device state data 


PNDEVSTATE 


Time data 


PNTIME 


Time data 


PNTM 


Accuracy data 


PNACCURACY 


Station data 


PNSTATION 


Device profile data 


PNDEV1CE 


Configuration data 


PNCONF1G 


Settings data 


PNSETTINGS 


Differential GPS status data 


PNDGPSSTATUS 


Almanac data 


PNAT MANAC 



30 



35 



PN_DT_POS]TJON 
PN_DT_ VELOCITY 
PN_DTJDEVICESTATE 
PN_DT_TIME 

PN_DT_TM 

PN_DT_ACCURACY 

PN_DT_STATION 

PN_DT_DEVICE 

PN_DT_CONFIG 

PN_DT_SETTINGS 

PN_ST_DGPSSTATUS 

PN DT ALMANAC 



Return Values S_OK 

Function succeeded. 
E_FAIL 

Unspecified error. 
E_INVALIDARG 

One or more arguments are invalid. 
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E_NOTIMPL 

Not implemented. 
PNAPI_EJDEVJCEUNAVAILABLE 

P&N device not available. 
5 PNAPI_E_STRUCTLOCKED 

Data structure is locked. 
PNAPI_E_NOCALLSTARTED 

No call has been started yet. 
PNAPI_E_NODATAYET 
1 0 No data has been received from the P&N device yet. 

Remarks PNAPI allows various OEM defined PNDataj structures to be 

passed through this function so that specific features can be made 
available. The quantity of available calls can be found within the 
1 5 header file included with this document. These calls start at 

PNDT_START_c and end at PN_DTJEND_c. OEM vendors 
should provide details about how they have implemented these 
OEM defined PNDataJ's. 

20 All data is received from the P&N device except PNCONFIG data 

which is taken from the registry. 



25 



The almanac data is -GPS specific and provide.* knowledge of the 
position of the satellites in the sky. 

See Also IPosNav::pnapiSetData, IPosNav::pnapiStartDirectCall 



30 IPosNavrrpnapiOpenDevice 

The IPosNavrrpnapiOpenDevice method is used to open 
communication with a GPS device. 

35 Syntax HRESULT pnapiOpenDevice ( 

phPNDevice phPN, 
pPNDEVICE pDevice 

); 

40 Parameters phPN 

Handle to a Pointing and Navigation device (phPNDevice 
is declared as LP VOID). If successful, a valid P&N 
handle is returned via this parameter. 
pDevice 

45 Pointer to the PNDEV1CE profile structure for the device 

to be opened. This structure is returned by 
pnapiFindDevices. 

Return Values S_OK 

Function succeeded. 
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E_FAIL 

Unspecified error. 
EJNVALIDARG 

One or more arguments are invalid. 
5 E_NOTIMPL 

Not implemented. 
E_OUTOFMEM OR Y 

Ran out of memory. 
REGDB_E_READREGDB 
1 0 Could not read key from registry. 

PNAPIJE_REGDBCLOSEKEY 

Can ! t close a registry key. 
PNAPI_E_LOADDLL 

Can't load DLL. 
15 PNAPI_E_DEVICEUNAVAILABLE 

P&N device not available. 

Remarks PNAPI allows multiple applications to use a P&N device 
simultaneously. An application should first use 
20 pnapiFindDevices to locate the device. When the first application 

opens a P&N device, PNAPI initializes the P&N device according 
to the control pane] sitings (initializing a rough position and - 
. ..... - time). When a second application opens the same P&N device, 

PNAPI does not initialize the P&N device a second time. 



25 



30 



35 



Close the P&N device using the CloseHandle function. 
See Also IPosNav::pnapiFindDevices, IPosNav::CloseHandle 

!PosNav::pnapiSetData 

The IPosNav::pnapiSetData method is used to send data to either 
the P&N device, or the registry. 



Syntax HRESULT pnapiSetData ( 

hPNDevice hPN 9 
LPVOID pBuffer, 
DWORD dwSixe, 
40 PNDataj Datajype 

); 

Parameters hPN 

Handle for the P&N device to use. 

45 pBuffer 

Pointer to a buffer to hold the data. The format is 
determined by DataJType. 

dwSize 

Size of pBuffer, in bytes. 
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DataJType 

Type of data to set. 



The supported data types are: 



Data Type 



Description 



Structure Type 



10. 



15 



20 



25 



30 



PNDTPOSITION 

PN_DT_ VELOCITY 

PN_DTJDEV1CESTATE 

PN_DT_TIME 

PN_DT_TM 

PN_DT_ A CGURAC Y 

PN_DT_STATION 

PNDTDEVICE 

PN_DT_CONFIG 

PN_DT_SETTINGS 

PN_DT_DGPSSTATUS 

PN DT ALMANAC 



Long,lat,alt position data 
Velocity data 
Device state data 
Time data 
Time data 
Accuracy data 
Station data 
Device profile data 
Configuration data 
Settings data 

Differential GPS status data 
Almanac data 



PNPOSITION 
PNVELOCITY 
PNDEVSTATE ' 
PNTIME 
PNTM 

PNACCURACY 

PNSTATION 

PNDEVICE 

PNCONFIG 

PNSETTINGS 

PNDGPSSTATUS 

PNALMANAC 



5 Return Values Return Value 



S_OK 
E_F AIL 

EJNVALIDARG 



Meaning 



E_NOTIMPL 

PNAPKE^DEVJCEUNAVAiLABLE 
PNAPI_E_NOACCESS 



Remarks 



35 



Function succeeded. 
Unspecified error. 
One or more 

'" nrgumems are . 
invalid. 

Not implemented. 
P&N device not 
available. 
Application has 
insufficient access 
rights. 

The position, time can be set to allow the P&N device to find its 
position more quickly. 

The configuration data in the PNCONFIG structure will be stored 
in the registry by this function. The settings contained will also 
be used to update the configuration of the P&N device. If any 
parameters do not apply to the P&N device, then they will be 
ignored by PNAPI. 

Almanac data is GPS specific and is received from the P&N 
device by the IPosNav::pnapiGetData or 

IPosNav::pnapiStartDirectCall function. The almanac details are 
stored in the registry only through the PNCONFIG structure. The 
almanac data should not be altered in any way. It provides 
accurate information about the GPS satellites' position at any one 
time. If almanac data is passed to this function, the system may 
be able to get a fix faster. 
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PNAPI allows various OEM defined PNDataj objects 
(structures, usually) to be passed through this function so that 
specific features can be made available. The quantity of available 
calls can be found within the header file included with this 
5 document. These calls start at PN JDT_START_c and end at 

PN_DT_END_c. OEM vendors should provide details abotiit how 
they have implemented these OEM defined PNDataj's. 

All data is sent to the P&N device except PNCONFIG data which 
10 is sent to the registry. 

Only applications with READ/WRITE access can use this 
function - the exception being when the user wishes to change 
access rights. 

15 

The PNTIME structure should contain a fairly accurate time in 
UTC (Universal Coordinated Time - also known as Greenwich 
meantime). 

20 See Also IPosNavrrpnapiGetData, IPosNav::pnapiStartDirectCall 



25 



IPosNav::pnapiStartCall 



The ]PosNav::pnapiStartCall method starts a call to get data from 
the P&N device and place it in PNAPI data structures. 



Syntax HRESULT pnapiStartCall. ( 

30 hPNDevice hPN, 

PNDataj Call, 
DWORD dwPeriod, 



); 

35 Parameters hPN 
Call 



The P&N device handle. 



Type of call to get from P&N device. All PNDataj calls 
valid for the pnapiGetData function can be used for Call 
40 dwPeriod 

Time period between updates of data, in milliseconds. If 
dwPeriod=0, only one call will be made. If dwPeriod=\ , 
the call can be made as rapidly as the device permits. 

45 Return Values SjOK 

Function succeeded. 
E_FAIL 

Unspecified error. 
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EJNVALIDARG 

One or more arguments are invalid. 
N_NOTIMPL 

Not implemented. 
5 PNAPIJ£_DEVICEUNA VAIL ABLE 

P&N device not available. 
PNAPI_E_DATAUNAVAILABLE 

Data unavailable. 
PNAPI_S_CALLALREADYSTARTED 
1 0 (Warning) Call already started. 

PNAPI_S_PERIODTOOSMALL 

(Warning) P&N device unable to support a call period as 

fast as that being requested. 

1 5 Remarks This method instructs the device to update its associated data 

structures at specified intervals. It enables a user to get the most 
recent data using the pnapiGetData method from the P&N 
device's data structures within PNAP1 as often as needed. 

20 See Also IP osNav::pnapiStopCall, IPosNav::pnapiGetData 



IPosNav::pnapiStartDireciCall 



The IPosNav::pnapiStartDirectCall method starts a call to get data 
from the P&N device. 



Syntax HRESULT pnapiStartDirectCall ( 

30 hPNDevice hPN, 



); 

Parameters hPN 
Call 



PNDataJ Call, 
DWORD dwPeriod, 
HWND hWnd 



The P&N device handle. 



Type of call to get from P&N device. All PNDataJ calls 
40 va 'id for the pnapiGetData ftmction can be used for Call 

dwPeriod 

Time period between updates of data, in milliseconds. 

hWnd 

The HWND that will receive messages informing the user 
45 that the data has been updated, and receive the data. 

Return Values S_OK 

Function succeeded. 
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E_FAIL 

Unspecified error. 
E_INVALIDARG 

One or more arguments are invalid. 
E_NOTIMPL 

Not implemented. 
PN API_E_DE VI CEUN A V AIL ABLE 

P&N device not available (Unplugged? Dead?). 
PNAPI_S_CALLALREADYSTARTED 

(Warning) Call already started. 
PNAPI_S_PER]ODTOOSMALL 

(Warning) P&N device unable to support a call period as 
fast as that being requested. 

1 5 Remarks Like pnapiGetData, this method allows the OEM defined 
PNData_t ! s to be used. For more information, see the 
pnapiGetData method. All data is received from the P&N device 
except PNCONFIG data which is taken from the registry. 

20 This method will get the requested data every dwPeriod, and then 

post a message to the owner window. The time between updates, 
dvsPeriod, \% in milliseconds, so presently calls of a period of >2 
weeks can be made. lfdwPeriod=0 then only one call will be 
made. If d^Period-l then the call will be made as rapidly as the 

25 P&N device will allow. OEMs should specify in their 

documentation the maximum and minimum periods that their 
P&N devices support. 

When data is received from the P&N device, PNAPI posts a 
30 WM_COPYDATA message. The LP ARAM parameter contains 

a COPYDATASTRUCT structure which contains two parameters 
- dwData and IpData. dwData specifies the type of data being 
passed. IpData is a pointer to the relevant structure cast to an 
LPVOID. See WM_COPYDATA notes in Win32 help for more 
35 information. 



UINT 


dwData 


IpData 


Meanine 


WM_COPYDATA 


PN_DT_P0S1T10N 


Pointer to 


PNPOSITION 






PNPOS1TION 


data has been 






data 


returned 


WM_COPYDATA 


PN_DT_ VELOCITY 


Pointer to 


PNVELOCITY 






PNVELOCJTY 


data has been 






data 


returned 


WM_COPYDATA 


PN_DT_TIME 


Pointer to 


PNTIME data 






PNTIME data 


has been 








returned 


WM_COPYDATA 


PN DT DEV1CESTA 


Pointer to 


PNDEVSTATE 




TE 


PNDEVSTATE 


data has been 






data 


returned 



5 



10 
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rN_D J _ACCURACY 


Pointer to 


PNACCURACY 




PNACCURACY 


data has been 




data 


returned 


PN_DT_STATION 


Pointer to 


PNSTATION , 




PNSTATION 


data has been 




data 


returned I 


PN_DT_CONFIG 


Pointer to 


PNCONIfIG data 




PNCONF1G data 


has been 
returned 


PN_DT_ALMANAC 


Pointer to 


PNALMANAC 




PNALMANAC 


data has been 




data 


returned 


PN_DT_SETTINGS 


Pointer to 


PNSETTINGS 




PNSETTINGS 


data has been 




data 


returned 



See Also IPosNav::pnapiStopDirectCall, IPosNav::pnapiGetData 

lPosNay::pnapiStopCasl - 

The IPosNav::pnapiStopCall method is used to stop a 
IPosNav::pnapiStartCall that has been .ita/ied. 



Syntax 



Parameters 



HRESULT pnapiStopCall ( 
hPNDevice hPN, 
PNData t Call 



); 

hPN 
Call 



The P&N device handle. 

Type of call to stop. All calls that are valid for the 
IPosNav::pnapiStartCall function are valid for the 
IPosNav::pnapiStopCall function. 

Return Values SJDK 

Function succeeded. 
E_FAIL 

Unspecified error. 
• EJNVALIDARG 

One or more arguments are invalid. 
E_NOTIMPL 

Not implemented. 
PNAPIJEJDEVICEUNAVAILABLE 

P&N device not available (Unplugged? Dead?). 
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PNAPI_E_NOC ALL STARTED 

No call has been started yet. 



5 



10 



Remarks If a call has been started (using IPosNav::pnapiStartGall) with a 
period of 0, then it does not need to be stopped with 
IPosNav::pnapiStopCall. A period of 0 indicates that the call is 
made only once, and then it is automatically stopped. 

See Also IPosNav::pnapiStartCall 



JPosNav::pnapiStopDirectCall 

1 5 The IPosNav::pnapiStopDirectCall method is used to stop a 

IPosNav::pnapiStartDirectCall that has been started. 

Syntax HRESULT pnapiStopDirectCall ( 

hPNDevice hPN, 
20 PNDatajCfl// 

); 

Parameters hPN 

The P&N device handle. 

25 Call 

Type of call to stop. All calls that are valid for the 
PosNav::pnapiStartDirectCaIl function are valid for the 
EPosNav::pnapiStopDirectCall function. 

30 Return Values S_OK 

Function succeeded. 
E_FAIL 

Unspecified error. 
EJNVALIDARG 
35 One or more arguments are invalid. 

E_NOTIMPL 

Not implemented. 
PNAPI_E_DEV1CEUNAVAJLABLE 

P&N device not available (Unplugged? Dead 4 ?) 
40 PNAPI_E_NOCALLSTARTED 

No call has yet been started. 

Remarks If a call has been started (using IPosNav::pnapiStartDirectCall) 
with a period of 0, then this call does not need to be stopped with 
45 IPosNavrrpnapiSlopDirectCall. A period of 0 indicates that the 

call is made only once, and then is automatically stopped. 

See Also IPosNav::pnapiStartDirectCall 
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IPosNav::pncnvBearingTo Velocity 

5 The IPosNav::pncnvBearingTo Velocity method is used to convert 

a bearing and two speeds to East, North and Up velocities. 

Syntax HRESULT pncnvVelocityToBearing ( 

const pPNVELENU pENUVel, 
1 0 pPNVELBEAR pBearVeh 

); 

Parameters pENUVel 

Pointer to a PNVELENU structure holding the velocity 
15 data. 

pBearVel 

Pointer to a PNVELBEAR structure holding the bearing 
data. 

20 See Also IPosNav::pncnvVelocityToBearing, PNVELENU, PNVELBEAR 



IPosNav::pncnvDegreesToRadians 

25 

The IPosNav::pncnvDegreesToRadians method is used to convert 
latitude/longitude/altitude data from degrees to radians. 

Syntax HRESULT pncnvDegreesToRadians ( 

30 pPNPOSLLA pLLAPos 

); 

Parameters pLLAPos 

Pointer to a PNPOSLLA structure containing the 
35 latitude/longitude/altitude data. The structure is returned 

with the same position in radians. 

Return Values SJDK 

Function succeeded. 
40 EJNVALIDARG 

One or more arguments are invalid. 

See Also IPosNav::pncnvRadiansToDegrees, PNPOSLLA 

45 
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IPosNavrrpncnvPNTMToWintm 

The IPosNav::pncnvPNTMToWintm method is used to convert 
time, in PNTM format, to Win32 SYSTEMTIME foimat. 

Syntax HRESULT pncnvPNTMToWintm ( 

PNTM pNTM, 

const SYSTEMTIME pTime, 

)> 



10 

Parameters pNTM 

The time to be converted, in PNTM format. 

pTime 

Receives the returned Win32 SYSTEMTIME formatted 
1 5 time. 

Return Values S_OK 

Function succeeded. 
E_FAIL 

20 Unspecified error. 

EJNVALIDARG 

One or move arguments are n. v::iicL 



25 



See Also IPosNav::pncnvWintmToPNTM, PNTM 



I PosNav: :pn cn vRadiansToDcgrees 

30 The IPosNav::pncnvRadiansToDegrees method is used to convert 

latitude/longitude/altitude data from radians to degrees. 

Syntax HRESULT pncnvRadiansToDegrees ( 

pPNPOSLLA pLLAPos 

35 ); 

Parameters pPLLAPos 

Pointer to a PNPOSLLA strucrure containing the 
40 latitude/longitude/altitude data. The structure is returned with the 

same position in degrees. 

Return Values S_OK 

Function succeeded. 
45 EJNVALIDARG 

One or more arguments are invalid. 

See also. IPosNav.-pncnvDegTeesToRadians, PNPOSLLA 
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JPosNav::pncnvVe)ocityToBearing 

The IPosNav::pncnvVelocityToBearing method is used to convert 
North/East/Up velocity data to a bearing and two speeds. 

Syntax HRESULT pncnvVelocityToBearing ( 
pPNVELBEAR pBearVel, 
const pPNVELENU pENUVel, 

10 

Parameters pBear Vel 

Pointer to a PNVELBEAR structure to hold the bearing 
data. 
pENUVel 

1 5 Pointer to a PNVELENU structure holding the velocity 

data. 

Return values S_OK 

Function succeeded. 
20 EJNVALIDARG 

One or more arguments are invalid. 

See Also IPosNav-pnc.nvBearingToVelocity, PNVELENU 

25 

IPosNav: :pn cn vWintmToPNTM 

The IPosNav-pncnvWintmPNTM method is used to convert time 
30 in Win32 format to PNTM format. 

Syntax HRESULT pncnvWintmPNTM ( 

const SYSTEMTIME pTime, 
PNTM pNTM, 

35 ); 

Parameters pTime 

The time to be convened, in Win32 SYSTEMTIME 
format. 

40 pNTM 

Receives the returned PNTM formatted time. 

Return values S_OK 

Function succeeded. 
45 E_FAIL 

Unspecified error. 
E_INVAL1DARG 

One or more arguments are invalid. 



SUBSTITUTE SHEET (RULE 26) 



WO 99/49394 
See Also 



107 

IPosNav::pncnvPNTMToWintm 
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IDGPS 



10 



15 



20 



25 



Remarks 



See Also 



The IDGPS interface provides methods to handle differential |GPS 
devices. 1 



Method 



IDGPS ::Close 
IDGPS ::GetRTCM 

IDGPS : :GetServiceQuality 
IDGPS::Open 



Description 



Closes a DGPS device 

Gets an RTCM message from a 

DGPS device 

Gets the DGPS service quality 
Opens a DGPS device 



The IDGPS interface contains a smaller set of methods that are 
needed to support differential GPS. 

Because of the variety of ways DGPS can be handled, this SDK 
only provides a definition of the IDGPS interface, not an 
implementation. To utilize DGPS, developers must create an 
object which exposes the JDGFS interface, alone wHh -whatever 
code is necessary for such tasks' as managing communication with 
the base station. The details of the IDGPS implementation will 
depend on the specifics of the particular DGPS system. 

IPosNav 



30 

IDGPS::Close 

The IDGPS::Close method is used to close a DGPS device. 

35 Syntax HRESULT Close (void); 

Parameters None 

Return Values SJDK 
40 Method succeeded. 

E_F All- 
Method failed. 



45 



See Also lDGPS::Open 
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IDGPS::GetRTCM 

The IDGPS::GetRTCM method gets a Radio Technical 
Commission for Maritime Service (RTCM) messaee from the 
5 DGPS device. 

Syntax 'HRESULT GetRTCM ( 

DWORD dwMessageJD 
PVOID pData 
10 DWORD dwSize 

); 

Parameters dwMessageJD 

The RTCM message number (in). 

15 pDaia 

Pointer to a buffer to store the returned RTCM messaee 
(out). 

dwSize 

The size of the structure being passed (out). 



20 



25 



40 



Return Values S_OK 

, . Metbo<Mailedv • - 

. E_FAiL ■ ;.' : 

Unspecified error. 



JDGPS::GetSemceQuality 



30 The IDGPS::GetServiceQuality method is used to determine the 

quality of support this DGPS service can provide. 

Syntax HRESULT GetServiceQuality ( 

DWORD &rdwMessage 
35 DWORD &rdwUpdateRate 

); 



Parameters rdwMessage 

Holds the DGPS service quality. rdwUpdateRate 

Holds the fastest rate that this DGPS service can hope to 
update its fastest RTCM message. 



Return Values S_OK 
45 Method succeeded. 

E_FAIL 

Method failed. 
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IDGPS::Open 

The IDGPS::Open method is used to open a DGPS device. 

5 

Syntax HRESULT Open (void); 

Parameters None 
] 0 Return Values S_OK 

Method succeeded. 
E_FAIL 

Method failed. 



15 See Also IDGPS::Close 
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Detailed Description of Data Structures for a Position and Navigation API 
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CHAPTER 19 
PN3State t 



10 



Enumerates a set of available modes. 
Constant Value Description 



PN_3S_FALSE 0 

PN_3S_TRUE 1 

PN_3S_OTHER 2 
position 



Off, or FALSE position 
On, or TRUE position 
Other, or indeterminate 



15 PNAccess_t 

Enumerates the access rights that the P&N device can supply to 
the application. 

20 Constant Value Meaning 

PN_AS_RE AD WRITE MINFNACCESS_7 P&ri' device has full z;xrj* 

rights 

PN_AS_READ MAX_PNACCESS_T P&N device has partial 

25 access rights ^aiiows user io 

only receive data from the 
P&N device). 

30 

PNACCURACY 

Stores accuracy details about the position supplied by the P&N 
device and the time these details were last updated. 

35 

typedef struct tagPNACCURACY 
{ 



DWORD 


dwStructureSize; 


PNTIME 


tiTime; 


PNDouble 


dHorizEnror; 


PNDouble 


dVerticalError; 


PNDouble 


dEDOP; 


PNDouble 


dNDOP; 


PNDouble 


dVDOP; 


PNDouble 


dPDOP; 


PNDouble 


dTDOP; 


PNDouble 


dGDOP; 


PNAVACCURACY 


acAvAccuracy; 


DWORD 


dwPNReserved; 
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} PNACCURACY; 

Members dwStructureSize 

The size, in bytes, of the structure. 

5 tiTime 

The time the data was received. 
dHorizError 

Not used by Windows CE. 
dVerticalError 
1 0 Not used by Windows CE. 

dEDOP 

East dilution of precision. 
dNDOP 

North dilution of precision. 
15 dVDOP 

Vertical dilution of precision. 

dPDOP 

Position dilution of precision. 
dTDOP 

20 Time dilution of precision. 

dGDOP 

-.- 7 : >Geometrie dihf-ion of precision" 1 " " " "'■(■^'■l 

acAvAccuracy 

Stores which elements of acAvAccuracy of are valid and 
25 which are not. 

dwPNReserved 

Reserved for future use by PNAPI. 

30 

PNALMANAC 

Stores GPS almanac details. 

35 typedef struct tagPN ALMANAC 

{ 

DWORD dwStructureSize; 

PNTIME tiTime; 

PNSATELLITE saSatellite (PN NUM SATS c): 

40 DWORD dwPNReservedl ~ " 

} PNALMANAC; 

Members dwStructureSize 

The size, in bytes, of the structure. 

45 tiTime 

Time data was collected. 
saSatellite 

Satellite information. 
dwPNReserved 



SUBSTITUTE SHEET (RULE 26) 



WO 99/49394 



113 



PCT/US99/06223 



Remarks 



Reserved for future use by PNAPI. 

The index number for each PNSATELL1TE structure is 
PRN#/SVID of the satellite in question. However, as the index 
number goes from 0-31, the index number+1 = PRN#/SVID. 

tiTime stores the time this almanac data was collected. To be ' 
precise, it is the time the first piece of satellite information was 
received. 



10 



PNAVACCURACY 



15 



Stores which PNACCURACY elements are valid and which are 
not. 



20 



25 Members 



30 



Name 



typedef struct tagPNAVACCURACY 
{ 

DWORD dwStructureSize 
DWORD dwAvl; 

- DWORD dwPNReserved: 
} PNAVACCURACY 

dwStructureSize 

The size, in bytes, of the structure. 

dwAvl 

The dwAvl parameter contains bit flags - one for each 
element in the corresponding PNACCURACY structure 
that shows whether the element is available. The 
following bit flags are defined for this structure: 



Bit Flae 



Meaning 



35 



40 



PN_AAC_AH ORJZERROR 0 
PN_AAC_AVERTlCALERROR 1 

PN_AAC_EDOP 2 

PN_AAC_NDOP 3 

PN_AAC_VDOP 4 

PN_AAC_PDOP 5 

PN_AAC_TDOP 6 

PN_AAC_GDOP 7 

Reserved for future use. 8-31 



Not used by Windows CE. 
Not used by Windows CE. 
EDOP valid / invalid. 
NDOP valid / invalid. 
VDOP valid / invalid. 
PDOP valid / invalid. 
TDOP valid / invalid. 
GDOP valid / invalid. 



45 



dwPNReserved 

Reserved for future use by PNAPI. 
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PNAVDEVSTATE 

Stores which DEVSTATE elements are valid and which are not. 

5 

typedef struct tagPNAVDEVSTATE 
{ 

DWORD dwStructureSize; 
DWORD dwAvl; 
10 DWORD wPNReserved 

} PNAVDEVSTATE; 

Members dwStructureSize 

The size, in bvtes, of the structure. 

15 dwAvl 

The dwAvl parameter contains bit flags - one for each 
element in the corresponding PNDEVSTATE structure 
that shows whether the element is available. The 
following bit flag is defined for this structure: 

20 

Name Bit Flag Meaning 

• PNADS_STATE Q Device statff-viM-*l$ivalid: 

Reserved for future use 1-31 

25 dwPNReserved 

Reserved for future use by PNAP1. 



30 PNAVDGPSSTATUS 

Holds status information for differential GPS. 

typedef struct tagPNAVDGPSSTATUS 
35 { 

DWORD dwStructureSize; 
DWORD dwAvl; 
DWORD dwPNReserved; 
} PPNAVDGPSSTATUS; 

40 

Members dwStructureSize 

The size, in bytes, of the structure. 

dwAvl 

TBD. 

45 dwPNReserved 

Reserved. 
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10 



15 



20 



25 



30 



35 



PNAV1NDSTAT10N 



Members 



Name 



Shows which PNINDSTATJON elements are valid and which are 
not. 

typedef struct tagPNAVINDSTATlON 
{ 

DWORD dwStructureSize; 
DWORD dwAvl; 
DWORD dwPNReserved; 
} PNAVINDSTATION; 

dwStructureSize 

The size, in bytes, of the structure. 

dwAvl 

The dwAvl parameter contains bit flags - one for each 
element in the corresponding PNINDSTATION structure. 
The following bit flags are defined for this structure: 

Bit Flag Meaning 



PN_ASI_STATE ......... 0. ;.- 

PN_ASi_STATlONIDNUM 1 

PN_ASI_USED 2 

PN_ASI_ELEVAT10N 3 

PN_ASI_SATAZ1MUTH 4 

PN_A SI_S IGN ALS TRENGTH 5 

PN_ASl_COVERAGE 6 

Reserved for future use. 7-31 



•'- Sifition str.tc vaiia? i)Yv5}id; : '* •"• 
JjiEiion ID number valid / invalid. 
fUsed parameter valid / invalid. 
Satellite elevatiun valid / invalid. 
Satellite azimuth valid / invalid. 
Signal strength valid / invalid. 
Not used by Windows CE. 



dwPNReserved 

Reserved for future use by PNAPI. 



PNAVPOSLLA 



40 



45 



Members 



Shows which of the position elements are valid. It is intended to 
mirror PNPOSLLA structure. 

typedef struct tagPNAVPOSLLA 
{ 

DWORD dwStructureSize; 
DWORD dwAvl; 
DWORD dwPNReserved; 
} PNAVPOSLLA; 

dwStructureSize 

The size, in bytes, of the structure. 
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10 



15 



dwAvl 

The dwAvl parameter contains bit flags - one for each 
element in the corresponding PNPOSLLA structure that 
shows whether the element is available. The following bit 
flags are defined for this structure: 

Name Bit Flag Meam'np 



PN_APL_LONG 0 

PN_APL_LAT J 

PN_APL_ALT 2 

PN_APL_RADIANS 3 

Reserved for future use. 4-3 1 



Longitude valid / invalid. 
Latitude valid / invalid. 
Altitude valid / invalid. 
fRadians parameter valid / invalid. 



dwPNReserved 

Reserved for future use by PNAPI. 



20 PNAVSATELL1TE 



25 



30 



35 



Members 



40 Name 



■■ Shows ;whkK : PN^ ^ 
not. . - " " "* " 

typedef struct tagPNAV^ATELLlTE * 
{ 

DWORD dwStructureSize; 
DWORD dwAvl; 
DWORD dwPNReserved; 
} PNAVSATELLITE; 

dwStructureSize 

The size, in bytes, of the structure. 

dwAvl 

The dwAvl parameter contains bit flags - one for each 
element in the corresponding PNSATELLITE structure 
that shows whether the element is available. The 
following bit flags are defined for this structure: 

Bit Flag Meaning 



PN_ASA_SETDATA 

PN_ASA_PRN 

PN_ASA_SATHEALTH 

45 PN_ASAJIEFWEEKNUMBER 

PN_ASA_REFTIMEOFWEEK 

PN ASA ECCENTRJCITY 



0 Not used by Windows CE. 

1 PRN# valid /invalid. 

2 Satellite heath valid / 
invalid. 

3 Reference week number 
valid / invalid. 

4 Referenced time of week 

valid / invalid. 

5 Eccentricity valid / invalid. 
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10 



15 



PNASA_ROOTSEMJMAJORAXIS 6 
PN_ASA_ARGUMENTOFPERIGEE 7 
PN_ASA_MEANANOMALYATREFTIME 8 
PN_ASA_RJGHTASCENS10NATREFTIME 9 



PN_ASA_RATERJGHTASCENSION 1 0 

PN_ASA_CORRJECTTOINCLINATION 1 1 

PN_ASA__AP0CLOCKCORRECT 12 

PN_ASA_AP1CL0CKC0RRECT 13 

Reserve for future use. ] 4.3 1 



Square root semi-major 
axis valid / invalid. 
Argument of perigee valid / 
invalid. 

Mean anomaly at reference 
time valid / invalid. 
Right ascension at reference 
time valid / invalid. 
Rate of right ascension 
valid / invalid. 
Correction to inclination 
valid / invalid. 
AFO clock correction valid / 
invalid 

AF1 clock correction valid / 
invalid. 



20 



dwPNReserved 

Reserved for future use by PNAPI. 



25 



PNAVSETTJNGS 



Shows which PNSETTINGS elements are valid and which are 
not. 



30 



35 



40 



Members 



Name 



typedef struct tagPNAVSETTINGS 
{ 

DWORD dwStructureSize; 
DWORD dwAvl; 
DWORD dwPNReserved; 
} PNAVSETTINGS; 

dwStructureSize 

The size, in bytes, of the structure. 

dwAvl 

The dwAvl parameter contains bit flags - one for each 
element in the corresponding PNSETTINGS structure that 
shows whether the element is available. The following bit 
flags are defined for this structure: 



Bit Flag 



Meaning 



45 



PN_ASE_MODE 0 

PN_ASEJDGPSENAJ3LE 1 

PN_ASE_DRENABLE 2 

PN_ASE_DGPSTIMEOUT 3 

PN_ASEJDGPS2DENABLE 4 



Not used by Windows CE. 
Enable differential GPS. 
Enable dead reckoning. 
DGPS timeout. 
Not used by Windows CE. 
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PN ASE DGPS2DTIME0UT 


5 




PN_ASE DATUM 


6 




PN_ASE POWERSTATE 


7 




PN_ASE ALT1TUDEHOLD 


8 


5 


PN ASE AHALTITUDE 


9 




PN_ASE 2DPOSMODE 


10 




PN_ASE_2DALTITUDE 


11 




PN ASE ENVIRONMENT 


12 




PN_ASE_ACCESS 


13 


10 


Reserved for future use. 


14-31 



Not used by Windows CE. 
Datum valid / invalid. 
Power state valid / invalid. 
Not used by Windows CE. 
Not used by Windows CE. 
Not used by Windows CE. 
Not used by Windows CE. 
Environment valid / invalid. 
Access rights valid / invalid. 



dwPNReserved 

Reserved for future use by PNAPI. 

15 



PNAVSTATION 

Shows which PNSTATION elements are valid and which are not. 

20 

typedef struct tagPNAVSTATION 

DWORD dwStrucrureSize; 

DWORD dwAvl; 

25 DWORD dwPNReserved; 

} PNAVSTATION; 

dwStructureSize 

The size, in bytes, of the structure. 

dwAvl 

The dwAvl parameter contains bit flags - one for each 
element in the corresponding PNSTATION structure that 
shows whether the element is available. The following bit 
flags are defined for this structure. 
35 

Name Bit Flag Meaning 

PN_ASN_NUMAVAJLABLE 0 Not used by Windows CE. 

PN_ASN_NUMUSED 1 Number stations used valid / 

invalid. 

40 Reserved for future use. . 2-31 

dwPNReserved 

Reserved for future by PNAPI. 

45 



Members 

30 



PNAVTM 



Stores which PNTM elements are valid and which are not. 
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10 



15 



20 



Syntax 



Members 



Name 



typedef struct taePNAVTM 
{ 

DWORD dwStructureSize; 
DWORD dwAvl; 
DWORD dwPNReserved; 
} PNAVTM; 

dwStructureSize 

The size, in bytes, of the structure. 

dwAvl 

The dwAvl parameter contains bit flags - one for each 
element in the corresponding PNTM structure that shows 
whether the element is available. The following bit flags 
are defined for this structure: 

Bit Flag Meaning 



PN_ATM_MILLJSEC 0 
PN_ATM_DAY 1 
Reserved for future use. 2-3 1 



Millisecond valid / invalid. 
Day valid / invalid. 



dwPNReserved 

Reserved for future use by PN API. 



25 ... 

PNAWELENU 

Shows which velocity elements are valid and which are not. 

30 typedef struct taePNAVVELENU 

{ 

DWORD dwStructureSize; 
DWORD dwAvl; 
DWORD dwPNResei^ed; 
35 } PNAWELENU; 

Members dwStructureSize 

The size, in bytes, of the structure. 

dwAvl 

40 The dwAvl parameter contains bit flags - one for each 

element in the corresponding PNVELENU structure. 
They show whether the element is available. The 
following bit flags are defined for this structure: 

45 Name , Bit Flag Meaning 

PN_AVN_EAST 0 East velocity valid / invalid. 

PN_A VNNORTH 1 North velocity valid / invalid. 

PN_A VNJJP 2 Up velocity valid / invalid. 

Reserved for future use. 3-31 
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dwPNReserved 

Reserved for future use. 



PNCONFIG 

Stores the data that goes into the registry as saved configuration 
10 data for this P&N device. 

typedef struct tagPNCONFIG 
{ 

DWORD dwStructureSize; 
15 PNPOSITION poPositionData; 

PNACCURACY acAccuracy; 

PNPOSITION poStaticRefPos; 

PNALMANAC alAlmanac; 

PNSETTINGS seSettings; 
20 PNBool flnitAlmanac; 

PNBool flnitPosition; 

PNBool . flniiTime: 

DWORD dwPNReserved; 
} PNCONFIG, 

25 

Members dwStructureSize 

The size, in bytes, of the structure. 
poPositionData 

Holds position and time it was found. Only PNPOSLLA 
30 portion used by Windows CE. 

acAccuracy 

Not used by Windows CE. 
poStaticRefPos 

Not used by Windows CE. 
35 alAlmanac 

Almanac data. 
seSettings 

Not used by Windows CE. 
flnitAlmanac 

40 Whether almanac will be initialized on start up. 

flnitPosition 

Whether position will be initialized on start up. 
flnitTime 

Whether the time will be initialized on start up. 
45 dwPNReserved 

Reserved for future use by PNAPL 
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Remarks 



PNData t 



10 



15 



20 



25 



30 



35 



All position data stored in these structures is stored in Longitude, 
Latitude, Altitude format in radians. If any structure contains a 
tiTime parameter, it shows when the data was gathered. 

Note: all values in the PNCONFIG structure go to the registry. 
No information is passed to the device. 



PNdataj enumerates the types of data to be used by functions 
such as pnapiGetData and pnapiSetData. 



Data Type 



40 



PN_DT ALL 
PN_DT~POSIT10N 

PN_DT_ VELOCITY 

PN_DT_DEV1 CESTATE 

• PN PT-IJME- • 
PN_DT_TM 
PN_DT_ACCURACY 

PN_DT_STATION 
PN_DT_DEV1CE 

PN_DT_CONFIG 

PN_DT_SETTINGS 

PN_DT_STAT1CREFP0S 
PN_DT_DGPSSTATUS 

PN_DT_RTCM1 
PN_DT_ALMANAC 

PN_DT_STATUS 
PN DT RESET 



Description 



All PNDatajs fields. 
Longitude, latitude, altitude 
position data (PNPOSLLA format). 
Velocity data (PNVELOCITY 
format). 

Device state data (PNDEVSTATE 
format). 
• Time data (PNTIME forma;}. 
Time data (PNTM fonnat). ' 
Accuracy data (PNACCURACY 
format). 

Station data (PNSTATION format). 
Device profile data (PNDEV1CE 
format). 

Configuration data (PNCONFIG 
fonnat). 

Settings data (PNSETTENGS 
fonnat). 

Not used by Windows CE. 
DiffGPS status data 
(PNDGPSSTATUS format). 
Not used by Windows CE. 
Almanac data (PNALMANAC 
format). 

Not used by Windows CE. 
Not used by Windows CE. 



PNDatum t 

45 

Enumerates the links between datum and datum code. 

Constant Value Meaning 

PN_DA_WGS84 0 World Geodetic System 1 984 
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Remarks Only WGS84 is valid. 



PNDEVICE 

The PNDEVICE structure contains a profile of a GPS device. In 
the case of multiple devices, the last element in the structure is a 
1 0 pointer to another PNDEVICE structure, and can be used to foim 

a linked list of structures. 

typedef struct tagPNDEVICE 
{ 

15 DWORD dwStructureSize; 

WCHAR szManufacturer [PN_MNFCT_SlZE_c]; 
WCHAR szModel [PN_MODEL_SlZE_c]; 
PNReceiver_trtReceiverType; 
DWORD dwUseCount; 
20 DWORD dwQuality; 

WCHAR szComPort [PN COM_PORT LEN_c]; 
■;- Xh WCHAR . szRegRoot fPIsCREG' r>vn-J. ^ikfijr]; ' 
■ DWORD dwComPort: 
DWORD dwPNReserved; 
25 struct tagPNDEVICE* pNext, 

} PNDEVICE; 

Members dwStructureSize 

The size, in bytes, of the structure. 
30 szManufacturer 

Not used by Windows CE. 
szModel 

The GPS chip manufacture and model name. 
rtReceiverType 
35 Not used by Windows CE. 

dwUseCount 

Number of applications that are currently using this 

device. 
dwQuality 

40 Quality of data this device can deliver (the lower the 

number the better it is). 
100 

Highest quality service. Supports all PNAPI 
features. 

45 200 

Rockwell/Trimble binary standard. Supports most 
PNAPI features. 
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300 

400 
500 
600 
700 
800 
900 



123 

Garmin standard. Supports not quite as many 
features as 200. 

NMEA V2.1 standard. Supports some features. 
NMEAV2.0/ VI. 5 standard. 
NMEA VI. 0 standard. 

Will support basic position and not much else. 
Will give position, but not necessarily altitude. 
Very basic support. 



szComPort 

Not used by Windows CE. 
szRegRoot 

For PNAPI internal use. 

pNext 

For multiple devices, pNext points to the next structure \n 

v..,!..-*.". a'linkeri-.liat; r-::- ~ : ::V:> : - -" 7 ' V." : ' ; ' : ^ '( 

dwComPort 

COM port in numerical format (see PN I *,?■?■ GPSl_c and 
PN_12P_GPS2Tc). 
dwPNReserved 

Resented for future use by PNAPI. 



30 

PNDeviceState 

Enumerates the possible device states. 
35 Slate Value 



Description 



PN_DS JNVAL1DDS - 1 000 

PN_DS_NOTPRESENT MIN_DEVICESTATE T 



40 PN DS ERROR 



1 



PN_DS_ WARNING 2 
45 PN_DS_OK 3 

PN DS SEARCHING 4 



//Device State is in 
invalid state. 
//Device not present 
(i.e. been unplugged) 
//Error in device 
making it not operate 
at all. 

//Error with device 
but can still operate. 
//Device 100% OK 
(but not yet 
searching). 
//Searchine for fix. 
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PN_DS_LEVEL1 


5 


//Found level 1 




PN_DS_LEVEL2 


6 


accuracy data. 
//Found level 2 


5 


PN_DS_LEVEL3 


7 


accuracy data. 
//Found level 3 




PN_DS_LEVEL4 


8 


accuracy data. 
//Found level 4 


10 


PN_DS_LEVEL5 


9 


accuracy data. 
//Found level 5 


PN_DS_LEVEL6 


10 


accuracy data. 
//Found level 6 




PN_DS_F0UND1SAT 


11 


accuracy data. 
//Found 1 satellite 


15 


PN_DS_FOUND2SATS 


12 


(GPS specific). 
//Found 2 satellites 




PN_DS_NOTIME 


MAX_DEVICESTATE_T 


(GPS specific). 
//No GPS time found 
(GPS specific). 



20 



PNDEVSTATE --,-„ ; 

Stores the P&N device state and what time it was last updated. 
25 " 
typedef struct tagPNDEVSTATE 
{ 

DWORD dwStmctureSize; 
PNTIME tiTime; 
30 PNDeviceStatej dsState; 

PNAVDEVSTATE dsAvState; 
DWORD dwPNReseived; 
} PNDEVSTATE; 

35 Members dwStructureSize 

The size, in bytes, of the structure. 

tiTime 

The time of the last update. 

dsState 

40 The device state. 

dsAvState 

Shows which dsState elements are valid and which are 
not. 

dwPNReserved 
45 Reserved for future use. 
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25 



30 



35 



40 



PNDGPSSTATUS 

Holds the differential GPS status. 

typedef struct tagPNDGPSSTATUS 
{ 

DWORD 

PNTIME 

PN3State_t 

PN3State_t 

PNBool 

DWORD 

PNAVDGPSSTATUS 
DWORD 
} PNDGPSSTATUS; 



dwStructureSize; 

tiTime; 

DGPSMode; 

OperatingMode; 

fDGPSStatus; 

dwDGPSAgeLimit; 

dpAvDGPSStatus; 

dwPNReserved; 



Members dwStructureSize 

The size, in bytes, of the structure. 

tiTime 

Time the data was gathered. 
DGPSMode 



Value 



PN_3S_FALSE 

PN_3S_TRUE 

PN_3S_OTHER 

OperatingMode 
Value 



Descri ption 



PN_3S_FALSE 
PN_3S_TRUE 
PN 3S OTHER 



DGPS off 
DGPS on 
Auto selection 



Description 



2D only 
3D only 
Auto selection 



fDGPSSstatus 

True, if outputting position with the receiver using DGPS 
corrections. 

False, if not using DGPS corrections. 
dwDGPSAgeLimit 

Maximum age to use, in milliseconds. 
dpAvDGPSStatus 

dwPNReserved 

Reserved for future use. 



45 

PNEnv t 



Pre-defined environments to which P&N devices can be set. 
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126 
Value 



Meaning 



PN_ET_STAT10NARY 
PN ET OPENROAD 



PN ET AIRCRAFT 



PN ET NONE 



PN ET USER 



MIN_PNENV_T 
1 



PN ET URBANCANYON 2 



PN_ET_FOREST 3 
PN ET OPENOCEAN 4 



MAX PNENV T 



Device is not 
moving. 

Device is on open 
road with clear view 
of sky. | 
Device is surrounded 
by tall city buildings. 
This is the 'City 1 
option in the GPS 
Control panel applet. 
Device is in a forest 
- or near trees. 
Device is on the 
open ocean with full 
view of sky. This is 
the 'Open water' 
option in the GPS 
Control panel applet. 
Device is in an 
aircraft with fill! 
'iew of ;*:ky. * 
No environment yet 
sei (only returned by 
PNSETTii 
TBD. 



30 PNINDSTATION 



35 



40 



45 



Stores individual station details and the time each was last 
updated. 



tvpedef struct tagPNINDSTATION 
{ 

DWORD 

PNTIME 

PNStationStatej 

DWORD 

PNBool 

PNDouble 

PNDouble 

PNDouble 

DWORD 

PNAVINDSTATION 
DWORD 
} PNINDSTATION; 



dwStructureSize; 

tiTime; 

ssState; 

dwStationDDNum; 
fUsed; 

dSatElevation; 

dSatAzimuth; 

dSignalStrength; 

dwCoverage; 

siAvIndStation; 

dwPNReserved; 
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Members 



10 



15 



20 



25 Remarks 



dwStructureSize 

The size, in byies, of the structure. 

tiTime 

Not used by Windows CE. 

ssState 

State of this station. 
dwStationEDNum 

PRN#/SVID or unique station number. 

fUsed 

Whether station is being used for calcns. 
dSatElevation 

Measured in radians (O-tc/2). 
dSatAzimuth 

Measured in radians (0-2 7t). 
dSignalStrength 

Signal strength, in dB. 
dwCoverage 

Not used by Windows CE. 
siAvIndStation 

Shows which PNINDSTATION elements are valid and 
which are not. 
dwPNReserved 

Reserved lor future use by PN API. 

For GPS receivers, dwStatwnlD is defined as the PRN or S V1D 
satellite number. Numbers 33-64 are reserved for WAAS. 
Numbers 65-96 are reserved for GLONASS. 



30 



If dwCoverage is zero, the period of coverage is not available, or 
is unreliable (i.e. highly variable). 



35 



PNPOSITION 



Stores the position and time at which this position was found. 



40 



45 



typedef struct tagPNPOSITION 
{ 

DWORD 
PNTIME 
PNPOSLLA 
PNAVPOSLLA 
DWORD 
} PNPOSITION; 



dwStructureSize; 
tiTime; 
psPosition; 
psAvPosition; 
dwPNReserved; 



Members dwStructureSize 

The size, in bytes, of the structure. 
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tiTime 

Time the position was acquired. 
psPosition 

The position. 
5 psAvPosition 

Which PNPOSLLA elements are valid. 
dwPNReserved 

Reserved for future use. 



10 



PNPOSLLA 



Contains position details in Longitude, Latitude and Altitude 
1 5 units. This is the standard units for the PNAPI. 

typedef struct tagPNPOSLLA 
{ 

PNDouble dLong; 

20 PNDouble dLat; 

PNDouble dAlt; 

PNBool . r . fRadums; 
} PNPOSLLA; 

25 Members dLong.. 

The longitude. 

dLat 

The latitude. 

dAlt 

30 Height above geoid in meters. 

fRadians 

TRUE if position (dLong and dLat) is in radians, FALSE 
if in degrees. Position is generally described in radians 
throughout PNAPI unless otherwise stated. 

35 



PNPowerState_t 

40 Enumerates the different power states the P&N device can have. 

Constant Value Meaning 

PN_PW_OFF MIN_PNP O WER S T A TE_T No power. 

PN_PW_SUSPENDED 1 ~ Device temporarily 

45 suspended. 

PN_PW_STANDBY 2 Device in standby 

mode. 

PNJPW_LOWPOWER 3 Device in low power 

mode. 
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PN_PW_MIDP0WER 4 
PN PW FULLPOWER 5 



Device in half power 
mode. 

Device in full power 
mode. 



10 



15 



20 



25 



30 



35 



40 



45 



PNRTCM1 

This structure contains the RTCM message. 

typedef struct PNRTCM1 
{ 

DWORD dwStructureSize; 

PNT1ME tiTime; 

BYTE ucRTCMMajorVersion; 

BYTE ucRTCMMinorVersion; 

PNRTCMHEADER Header; 

BYTE ucNumSats; 

PNRTCM1SAT SatData 

(PN_NUM_RTCM1_SATS c): 
■ . PN3y*s . bRivData 

. - ■ " (PN_RTCM 1 _M AXJBYTE LEN 

c); 

DWORD dwPNReservsd, 
} PNRTCM1; 

typedef PNRTCM 1 * pPNRTCM 1 ; 

Members dwStructureSize 

Size of the structure. 

tiTime 

The time (as a PNTIME structure). 
ucRTCMMajorVersion 

Major version number. 
ucRTCMMinorVersion. 

Minor version number. 

Header 

Message header. 
ucNumSats 

Number of valid satellites in SatData. 
SatData 

The satellite data. 
bRawData 

The raw data. 

Remarks This structure definition is provided for the use of application 
developers implementing DGPS objects. 
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PNRTCM1SAT 

This structure contains satellite data for DGPS. 

typedef struct PNRTCM 1 SAT 
{ 



Members 



Remarks 



DWORD 


dwStructureSize; 


PNBool 


fScaleFactor; 


BYTE 


ucUDRE; 


BYTE 


ucSatellitelD; 


WORD 


uPsCorrection; 


BYTE 


ucRRateCorrection; 


BYTE 


ucIssueOiData; 


DWORD 


dwPNReserved; 



} PNRTCM] SAT; 

dwStructureSize 

Size of the structure. 
AScaleFactor 

ucUDRE 

ucSatellitelD 

Satellite ID. 
uPsCorrection 

ucRRateCorrection 

ucIssueOfData 

This structure definition is provided for the use of application 
developers implementing DGPS objects. 



35 PNRTCMHEADER 



This structure contains the header for an RTCM message. 

typedef struct tagPNRTCMHEADER 
40 { 



DWORD 


dwStructureSize; 


BYTE 


ucMessageType; 


WORD 


uStationlD; 


WORD 


uModZCount; 


BYTE 


ucSequenceNum; 


BYTE 


ucFrameLength; 


BYTE 


ucStationHealth; 


DWORD 


dwPNReserved; 


} PNRTCMHEADER; 
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15 



Members dwSlructureSize 

Size of the structure. 
ucMessageType 

Message type (frame ID). 
uStationJD 

Station ID. 
uModZCount 

?? 

ucSequenceNum 

Sequence number. 

ucFrameLength 

Frame length. 

ucStationHealth 

Station health. 



Remarks 



20 



This structure definition is provided for the use of application 
developers implementing DGPS objects. 



PNSATELLITE 



25 



30 



35 



40 



45 



Stores individual satellite data, 
typcdcf struct tagPNSATELLITE 



{ 

DWORD 
PNTIME 
PNBool 
DWORD 
PNByte 
DWORD 
DWORD 
PNDouble 
PNDouble 
PNDouble 
PNDouble 
PNDouble 
PNDouble 
PNDouble 
PNDouble 
PNDouble 
PNAVSATELLITE 
DWORD 
} PNSATELLITE; 



dwStructureSize; 

tiTime; 

fSetData; 

dwPRN; 

bSatHealth; 

dwRefWeekNumber; 

dwRefTimeOfWeek; 

dEccentricity; 

dRootSemiMajorAxis; 

dArgumentOfPerigee; 

dMeanAmomalyAtRefTime; 

dRightAscensionAtRefTime; 

dRateRightAscension; 

dCorrectToInclination; 

dAFOClockCorrect; 

dAFl ClockCorrect; 

saAvSatellite; 

dwPNReserved; 



Members dwStructSize 

The size, in bytes, of the structure. 
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tiTime 

Not used by Windows CE. 
fSelData 

Not used by Windows CE. 
5 dwPRN 

Satellite PRN number. 
bSatHealth 

Health summary (binary). 
dwRefWeekNumber 
1 0 GPS week number. 

dwRefTimeOfWeek 

Almanac reference time. 
dEccentricity 

Eccentricity. 
1 5 dRootSemiMajorAxis 

Measures in meters A 0.5. 
dArgumentOfPerigee 

Measured in radians. 
dMeanAnomolyAtRefTime 
20 Measured in radians. 

dRightAscensionAtRefTime. 

Measured in radians. 
dRateRightAscension 

Measured in radians/sec. 
25 dCorrectTolnclination 

Measured in PI radians. 
dAFOClockCorrect 

Measured in seconds. 
dAFlClockCorrect 
30 Measured in sec/sec. 

saAvSatellite 

Which elements are valid. 
dwPNReserved 

Reserved for future use by PNAPI. 

35 

Remark IhtfSetData parameter is used in the pnapiSetData function. If 
set, it updates the GPS receiver's almanac with this satellite's data. 
If not, this structure is not sent to the GPS receiver. When this 
structure is received through the pnapiGetData or 
40 pnapiStartDirectCall function, the fSetDaia parameter has no 

meaning and should be set to zero. 



45 PNSETT1NGS 

Stores P&N device settings that can be changed by the user, 
typedef struct tagPNSETTINGS 
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{ 

DWORD 
PNTIME 

PNSTATIONMODE 

PNBool 

PNBool 

DWORD 

PNBool 

DWORD 

PNDatumj 

PNPowerStateJ 

PNAltHoldJ 

PNDouble 

PN2DModej 

PNDouble ~~ 

PNAccess_t 

PNEnvj 

PNAVSETTINGS 
DWORD 
} PNSETTINGS; 



dwStructureSize; 
tiTime; 

cmMode[PN NUM_SATS_c]; 

fDGPSEnable; 

fDREnable; 

dwDGPSTimeOut; 

fDGPS2DEnable; 

dwDGPS2DTimeOut; 

daDatum; 

pwPowerState; 

ahAltitudeHold; 

dAHAltitude; 

mo2DPosMode; 

d2DAltitude; 

asAccess; // 

etEnvironment; 

seAvSettings; // 

dwPNReserved; // 



dwStructureSize 

The size, in bytes, of the structure. 

tiTime 

The time when the data was gathered. 
cmMode 

Not used by Windows CE. 
fDGPSEnable 

Enables/disables DGPS functionality. 
fDREnable 

Enable/disables dead reckoning functionality. 
dwDGPSTimeOut 

Sets/gets the DGPS time out (in milliseconds). 
fDGPS2DEnable 

Not used by Windows CE. 
dwDGPS2DTimeOut 

Not used by Windows CE. 
daDatum 

Datum receiver uses. 
pwPowerState 

Power state of device. 
ahAltitudeHold 

Not used by Windows CE. 
dAHAltitude 

Not used by Windows CE. 
mo2DPosMode 

Not used by Windows CE. 
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d2DPosMode 

Not used by Windows CE. 
d2DAhitude 

Not used by Windows CE. 
5 asAccess 

Access rights for device. 
etEnvironment 

Environment for this device. 
seAvSettings 

1 0 Which elements are valid. 

dwPNReserved 

Reserved for future use by PNAPI. 



15 

PNSTATION 

Contains the details for all stations the P&N device has access to. 

20 typedef struct tagPNSTATlON 

{ 

DWORD '■ dvvStrjcturf.Si;:e; " ■ ' 

PNT1ME tiT:me; 

DWORD dwNumA viable; /' 

25 DWORD dwNumUsed, 

PNAVSTATION snAvStation; 

PNINDSTATION siStations 

[PN_NUM_STATIONS_c]; 

DWORD dwPNReserved; 
30 } PNSTATION; 

Members dwStructureSize 

The size, in bytes, of the structure. 

tiTime 

35 The time the structure was last updated. 

dwNumAvailable 

Not used by Windows CE. 
dwNumUsed 

Number of stations being tracked by the device. 
40 snAvStation 

Stores which elements of PNSTATION of are valid and 
which are not. 
siStations 

Individual station data. 
45 dwPNReserved 

Reserved for future use by PNAPI. 
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PNStationSfateJ 

Enumerates the station states. 



Constant _ 

PN_CS_UNAVAJLABLE 0 

PN_CSJDLE l 

PN_CS_SEARCHING 2 

PNJTSJTRACKJNG 3 



Value 



Description 



Station unavailable.. 
Station idle. j 
Station searching for 
data. 

Station finding good 
data. 



15 PNTIME 



20 



25 



30 



35 



40 



Members 



Stores P&N device time and computer system time. 



typedef struct tagPNTIME 
{ 

PNTM 

PNAVTM 

PNAVTM 
PNTM 
PNAVTM 
} PNTIME; 



tmDevice; 

trnAvDcyscci 
tmLeapDj i'i'i ime; 
tmAvLeapDiffTime; 
tmComputKy - 
tmAvComputer; 



tmDevice 

The time reported by the device. 
tmAvDevice 

Stores which elements of tmAvDevice are valid and which 

are not. 
tmLeapDiffTime 

Not used by Windows CE. 
tmAvLeapDiffTime 

Not used by Windows CE. 
tmComputer 

The system time on the computer. 
tmAvComputer 

Stores which elements of tmAvComputer are valid and 

which are not. 



45 



PNTM 



Stores time to the millisecond. 
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typedef struct tagPNTM 
{ 

DWORD dwMillisec; 
DWORD dwDay; 
5 } PNTM; ' 

Members dwMillisec 

Milliseconds since start of day (0-86400000). 

dwDay 

10 Days since Jan P 1900. 



PNVELBEAR 

15 

Contains velocity details in the form of a bearing and two 
velocities. 

rypedef struct tagPNVELBEAR 
20 { 

PNDoubledBearing; 

PMDoubledHorizSpeed; ::r 
."•■••■* • i-NDoubledVenSpecd;' r 
} PNVELBEAR; 
25 . ... r - / : ■': ....... 

Members dBearing 

(Wearing has a ranee from -PI to +PI. Zero is North. 
dHorizSpeed 

Horizontal speed in meters/sec. 
30 dVenSpced 

Vertical speed in meters per second. 



35 PNVELENU 

Contains velocity details in the East, North, Up format. 

typedef struct tagPNVELENU 
40 { 

PNDouble East; 
PNDouble North; 
PNDouble Up; 
} PNVELENU; 

45 

Members East 

East velocity, in meters/second. 

North 

North velocity, in meters/second. 
SUBSTITUTE SHEET (RULE 26) 
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Up 

Up velocity, in meters/second. 

Remarks A westward velocity is expressed as a negative East velocity and 
a southward velocity is expressed as a negative North velocity. 

PNVELOCITY 

Stores velocities and the time they were last updated. 



5 



typedef struct tagPNVELOCITY 
{ 

15 DWORD dwStmctureSize; 

PNT1ME tiJime; 

PNVELENU vlVelocity; 

PNAVVELENU vlAvVelocity; 

DWORD dwPNReserved; 
20 } PNVELOCITY; 

Members. . dwStmctureSize "~ : ■ 

~'fhe size, in bytes, of the structure. 
tiTime 

25 The time. 

vlVelocity 

The velocity. 
vlAvVelocity 

Shows which vlVelocity elements are valid and which are 
30 not. 

dwPNReserved 

For future use. 
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Detailed Description of a Handwriting Recognition API 



SUBSTITUTE SHEET (RULE 26) 



WO 99/49394 PCT/US99/06223 

139 

Module/component: 

Platforms: WPC 

Windows CE versions: 2.02 and later 

5 Parameters hVol 

VOL structure returned from FSDMGR ReeisterVolume. 
hProc " 

Originating process handle. 
pSearch 

1 0 FSD-defined search-specific data for the new handle. 

Return Values If the function is successful, it returns a search handle associated 
with the originating process. If it is unsuccessful, it returns 
INVALID_HANDLE_VALUE. 



15 



20 



30 



35 



Remarks FSDMGR_RegisterVolume 
See Also 



HwxConfig 

The HwxConfig function initializes the handwriting recoenition 
25 dynamic-link library (DLL). 

Syntax BOOL HwxConfig ( 

void 

); 

At a Glance Header file: Recog.h 
Module/component: 

Platforms: H/PC 

Windows CE versions: 2.0 and later 

Return Values If the function is successful, it returns TRUE. If an error occurred 
initializing the handwriting recognition engine, the function 
returns FALSE. 

40 ^ ^ is unsuccessful, use GetLastError to identify the cause of the 

error. 



Remarks This function is called only once by each application to initialize 
the DLL. 



45 
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HwxCreate 

The HwxCreate function creates a handwriting recognition 
context (HRC) object for the recognizer. 

Syntax HRC HwxCreate ( 

HRC hrc 

); 

10 At a Glance Header file: Recog.h 
Module/component: 
Platforms: H/PC 
Windows CE versions: 2.0 and later 

15 Parameters hrc 

Handle to an existing HRC object that provides settings 
for the recognition context being created. If it is NULL, 
then default settings are used. 

20 Return Values If the function is successful, it returns the handle to the newly 
created HRC object; otherwise, it returns NULL. 

if HwxCreate fails/use GetLastError to get error information. 
25 Remarks Tin's function is called before any ink is collected. 

The hrc parameter is used to copy an old context's settings into 
the new HRC object. These settings include word lists, coercion, 
and the HWXGUIDE structure, but exclude any pen data that may 
30 be in the old context. 

See Also HwxDestroy, HWXGUIDE 



35 



HwxDestroy 



40 



The HwxDestroy function destroys a handwriting recognition 
context (HRC) object. 



Syntax BOOL HwxDestroy ( 

HRC hrc 

); 

45 At a Glance Header file: Recog.h 
Module/component: 
Platforms: H/PC 
Windows CE versions: 2.0 and later 
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Parameters hrc 

Handle to the HRC object. 

Return Values If the function is successful, it returns TRUE. Iftherewasan 
invalid parameter or other error, it returns FALSE. 

If this function fails, call GetLastError for error information. ' 

This function is called to destroy an HRC after recognition is 
complete. After HwxDestroy returns TRUE, the handle hrc is no 
longer valid. The application should set hrc to NULL to ensure it 
is not inadvertently used again. 



15 

HwxSetGuide 



Remarks 

10 



20 



25 



30 



35 



The HwxSetGuide function identifies the location of the boxes on 
the screen for a specified handwriting recognition context (HRC). 

Syntax BOOL HwxSetGuide ( 

HRC hrc, 
" ' HWXGUIDE* IpGuide 

); 

At a Glance Header file: Recog.h 
Module/component: 

Platforms: H/PC 

Windows CE versions: 2.0 and later 



Parameters hrc 



Handle to the HRC object. 



IpGuide 

Pointer to a HWXGUIDE structure. 

Return Values If the function is successful, it returns TRUE. If the function is 
unsuccessful, it returns FALSE. 



40 



45 



If the function fails, use GetLastError to get error information. 

Remarks This function is used for doing boxed recognition. The GUIDE 
structure defines the size and position of the boxes. If IpGuide is 
NULL, or if all the members in the GUIDE structure are 0, the 
recognizer does not use guides. This is also known as free input. 

See Also HWXGUIDE 
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HwxALCValid 

The HwxALCValid function defines the set of characters that the 
recognizer can return. 

5 

Syntax BOOL HwxALCValid ( 

HRC hrc, 
ALCalc 

); 

At a Glance Header file: Recog.h 
Module/component: 
Platforms: p/PC 
Windows CE versions: 2.0 and later 

Parameters hrc 



10 



Handle to the handwriting recognition context (HRC) 
object. 

ale 

20 ALC value that describes the character grouping that is 

used by the recognizer to evaluate the input handwriting 
It can be one or more of }o wing value i-: 
ALC_WHITE 

White space. 
25 ALC_LCALPHA 

The lowercase alphabet, a through z. 
ALCJJCALPHA 

The uppercase alphabet, A through Z. 
ALCNUMERJC 
30 0 through 9. 

ALC_PUNC 

Standard punctuation, language dependent. 
ALCJ\njMERJC_PUNC 

Non-digit characters in numbers. 
35 ALCMATH 

% A *(L+{}</ (???Language dependent???) 
ALC_MONETARY 

Punctuation in local monetary expressions. 
ALC_COMMONSYMBOLS 
40 Commonly used symbols from all categories. 

ALC_OTHER 

Other punctuation not typically used. 
ALC_ASCII 

7-bit characters - 20 through 7F. 
45 ALCHIRAGANA 

Hiragawa. 
ALC_KATAKANA 
Katakana. 
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ALC_KANJl_COMMON 

Common Kanji (JPN). 
ALC_KANJ1_RARE 
ALC_HANGUL_COMMON 

Common Hangul used in Korea. 
ALC_HANGUL_RARE 

The rest of Hangul used in Korea. 
ALC_UNUSED 

Reserved for future use. 
ALC.OEM 

OEM recognizer specific. 



Useful groupings, by 
combining two or more 
of the basic ALC 
groupingsuseful ALC 
groupings 



definition 



ALC_ ALPHA 

ALC_ ALPHANUMERIC 

ALC_KANA 

ALC_KANJ1_ALL 

ALC_HANGUL_ALI. 

ALC_EXTENDEB_SYM 

ALC_SYS_MIN1MUM 

ALC-SYS-DEFAULT 



Standard combinations for 
various languages.language 
ALC groupings 



ALC_LCALPHA | ALC UCALPHA 
ALC_ ALPHA | ALC_NUMERJC 
ALC_H1RAGANA | ALC_KATAKANA 
ALC_KANJI_COMMON | ALC_KANJ1 RARE 
.. ALC.RAJ^GlJJ^COMMOii !^. ..... . ~ 

ALC HANGUL RARE " 
ALC_MATH | ALC_M ONETA RY | 

ALC_OThER 
ALC- ALPHANUMERIC | ALC_PUNC | 

ALC_WH1TE 
ALC_SYS_MINIMUM | 

ALC_COMM ON_S YMBOLS 

definition 



ALC_USA_COMMON ALC 

ALC_USA_EXTENDED ALC 

ALC_JPN_COMMON ALC 

ALC_JPN_EXTENDED ALC 

ALC_CHS_COMMON ALC. 

ALC_CHS_EXTENDED ALC. 

ALC_CHT_COMMON ALC 



_SYS_DEFAULT 
_USA_COMMON | 

ALC_EXTENDED_SYM 
_SYS_DEFAULT | ALC_KANA | 

ALC_KANJI_COMA10N 
.JPN_COMMON | ALC_EXTENDED_SYM 

| ALC_KAN J I_RARE 
SYS_DEFAULT | 

ALC_KANJI_COMMON 
CHS_COMMON| 

ALC_EXTENDED_SYM | 

ALC_KANJI_RARE 
SYS_DEFAULT | 

ALC_KANJI COMMON 



SUBSTITUTE SHEET (RULE 26) 



WO 99/49394 



PCT/US99/06223 



144 



10 



15 



20 



ALC_CHT_EXTENDED ALC_CHT_COMMON | 

ALCJEXTENDED_SYM | 
ALC_KANJI_RARE 

ALC_KOR_COMMON ALC_SYS_DEFAULT | 

~ ALC_HANGUL_COMMON | 
ALCJ(ANJI_COMMON 

A1C_K0R_EXTENDED ALC_KOR_COMMON | 

ALC_EXTENDED SYM | 
ALC_HANGUL_RARE | 
ALC_KANJI_RARE 

Retum Values If the recognizer is set to recognize the specified ALC grouping, 
the function returns TRUE. If the recognizer is not set, the 
function returns FALSE. 

If HwxALCValid fails, use GetLastError for error information. 

Remarks This function tells the recognizer which characters to use to 
evaluate the ink in the HRC. 



HwxALCPriority 

25 : The Hwx ALCPriority function reorders the characters returned by 

the recognizer so that selected characters appear at the top of the 
list. 

Syntax BOOL HwxALCPriority ( 

30 ERChrc, 

ALC ale 

); 

At a Glance Header file: Recog.h 
35 Module/component: 

Platforms: H/PC 
Windows CE versions: 2.0 and later 



40 



45 



Parameters hrc 



ale 



Handle to the handwriting recognition context (HRC) 
object. 

ALC value that describes the character grouping that will 
be used by the recognizer to ???????. 

Return Values If the recognizer has been reset for the selected characters, the 

function returns TRUE. The function returns FALSE otherwise. 
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If this function fails, use GetLastError to identify the cause of the 
error. 

Remarks ????????? need to describe how this works ^ww 

5 

See Also HwxALCValid 



10 HwxSetPartial 

The HwxSetPanial function sets the recognizer parameter for 
partial recognition. 

15 Syntax BOOL HwxSetPanial ( 

HRC hrc, 
UENT urecog 

); 

20 At a Glance Header file: Recog.h 
Module/component: 
Platforms: H/PC 
Windows CE versions: 2.0 and later 

25 Parameters hrc . 

Handle for the recognition context (HRC) object. 

urecog 

Value for the partial recognition parameter. It can be one 
of the following values: 

30 , ????????????? 

Return Values If the recognizer is set with the partial recognition value, the 

function returns TRUE. The function returns FALSE otherwise. 

35 If HwxSetPanial fails, use GetLastError for error information. 

Remarks ?????????? describe partial recognition ???????????? 

40 

HwxSetAbort 

The HwxSetAbort function sets the abort address. 

45 Syntax BOOL HwxSetAbort ( 

HRC Arc, 

void* * ppabortaddr 

); 
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At a Glance Header file: Recog.h 
Module/component: 

Platforms: H/PC 

Windows CE versions: 2.0 and later 

Parameters hrc 

Handle of the handwriting recognition context (HRC) < 
object. 
ppaboriaddr 

???????? pointer to a pointer to the abort address ???????? 

Return Values If the, recognizer is set with the abort address, the function returns 
TRUE. The function returns FALSE otherwise. 

1 5 If HwxSetAbort fails, use GetLastError for error information. 

Remarks ????????? describe why you use this ???????????? 



10 



20 



Hwxlnput 



25 



The H^li ip ii* jfh^o fi -^ ds ink U) th:; : ^ V;dwrili reco ^: lion 
coniext (HRC). 



Syntax BOOL Hwxlnput ( 

HRC Arc, 
POINT* Ippnt, 
UINT upoints, 
30 DWORD timestamp 

); 

At a Glance Header file: Recog.h 
Module/component: 

35 Platforms: H/PC 

Windows CE versions: 2.0 and later 

Parameters hrc 

Handle to the HRC object. 

40 Ippnt 

Address of an array of POINT structures. The information 
in the POINT structures should be scaled to match the 
HWXGUIDE structure. 

upoints 

45 Number of POINT structures. 

timestamp 

Time stamp of the first mouse event in the stroke. The 
time stamp should be taken directly from the MSG 
structure for the mouse down event. 



SUBSTITUTE SHEET (RULE 26) 



WO 99/49394 



147 



PCT/US99/06223 



Return Values If the function is successful, it returns TRUE. If there is an 
invalid parameter or other error, it returns FALSE. 

5 If this function fails use GetLastError for error information. 

Remarks This function adds ink to the HRC object one stroke at a timcj. It 
takes the array of points, the count of the points, and the time 
stamp of the first mouse event in the stroke and adds it to the 
10 HRC object. 

See Also HWXGUIDE, POINT 



15 



25 



30 



HwxEndlnput 



The HxwEndlnput function tells the recognizer that no more ink 
should be added to the handwriting recognition context (HRC) 
20 object. 

Syntax BOOL HwxEndlnwut ( - • 

); 



At a Glance Header file: Recog.h 
Module/component: 

Platforms: H/PC 

Windows CE versions: 2.0 and later 

Parameters hrc 

Handle to the HRC object that is to be closed. 



Return Values If the HRC is closed, the function returns TRUE; otherwise, it 
35 returns FALSE. 

Remarks This function is called after the last ink is added to the HRC. The 
next call to HwxProcess completes recognition on all the input. 
Any calls to Hwxlnput on this HRC fail after HwxEndlnput is 
40 called. 

See Also Hwxlnput, HwxProcess 



45 
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HwxProcess 

The HwxProcess function signals the recognizer to analyze the 
information in the specified handwriting recoenition context 
(HRC) object. 

Syntax BOOL HwxProcess ( 

HRC hrc 

At a Glance Header file: Recog.h 
Module/component: 

Platforms: H/PC 

Windows CE versions: 2.0 and later 

Parameters hrc 

Handle to the HRC object to be analyzed. 



ReUirn Values If the recognition is completed, the function returns TRUE. If 
20 there is an invalid parameter or other error, it returns FALSE. 

Remarks This function processes the ink that has been re reived by the 

HRC object. Full recognition occurs only after HwxEndlnput is 
called. The application must then call HwxGetResults to obtain 
25 recognition results. 

There is no support for timeouts. 

If the function fails, use GetLastError for error information 

30 

See Also HwxEndlnput, HwxGetResults 



35 HwxGetResults 

The HwxGetResults function retrieves the results from the 
recognition on the handwriting recognition context (HRC). 

40 Syntax INT32 HwxGetResults ( 

HRC hrc, 

UTNT cAlt, 

UINT iFirsU 

UINT cBoxRes, 
45 HWXRESULTS *rgBoxResults 

); 
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At a Glance Header file: Recog.h 
Module/component: 

Platforms: H/PC 

Windows CE versions: 2.0 and later 



Parameters hrc 



cAlt 



Handle to the HRC object used for input. 



10 



15 



20 



25 



30 



Number of alternate results expected in the 
HWXRESULTS structure. If this parameter is 0, the 
function returns 0. 

xFirst 

Index of the first character to return. 
cBoxRes 

Number of characters to return. 
rgBoxResults 

Array of cBoxRes-ranked lists. 

Return Values If the function is successful, it returns the number of characters 
actually returned; otherwise, it returns HRCR_ERROR, which 
indicates an invalid parameter or other error. 

Remarks ' This function retrieves the results from an HRC object used for 
boxed input. It simplifies the task of boxed recognition by 
providing character alternatives on a per-box basis in one call. 
This function may be called repeatedly, allowing you to get 
results for several characters at a time. The results for the 
returned characters are put in the rgBoxResults buffer that was 
passed in. 

See Also HWXRESULTS 



35 HwxSet Context 



The HwxSetContext function adds context information to the 
handwriting recognition context (HRC). 

40 Syntax BOOL HwxSetContext ( 

HRC hrc, 

WCHAR WchContext 

); 

45 At a Glance Header file: Recog.h 
Module/component: 
Platforms: H/PC 
Windows CE versions: 2.0 and later 
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Parameters hrc 

Handle to the HRC object. 
WchConiext 

Character of prior context to the characters contained in 
the HRC. If this parameter is 0, it clears the context 
information. j 

! 

Return Values This function returns TRUE if successful; if there was an invalid 
parameter or other error, it returns FALSE. 

If the function fails, use GetLastError for error information. 



Remarks Handwriting recognition performance can be improved if the 

recognizer has context information available during processing. 
15 Context information is added to an HRC by using 

HwxSetContext, which provides one character of prior context for 
the recognizer. This function should be called prior to using the 
HwxProcess function. If this function is not called, the recognizer 
assumes that no prior context is available. 



See Also HwxProcess 



25 HwxResults Available 



The HwxResultsAvailable function returns the number of 
characters available for HwxGetResults to retrieve. 

30 Syntax INT HwxResultsAvailable ( 

HRC hrc 

); 

At a Glance Header file: Recog.h 
35 Module/component: 

Platforms: H/PC 
Windows CE versions: 2.0 and later 

Parameters hrc 

40 Handle to the handwriting recognition context (HRC) 

object. 



Return Values Number of characters available for HwxGetResults to retrieve. It 
returns -1 on error. 

If the function fails, use GetLastError for error information. 

Remarks This function allows characters to be retrieved before all the input 
has been added to the HRC. 
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See Also HwxGetResults 



5 

GetThreadTimes 

The GetThreadTimes function obtains timing information about a 
specified thread. 

10 

Syntax BOOL GetThreadTimes ( 

HANDLE hThread 
LPFJLETIME IpCreationTime, 
LPFILETIME IpExitTime, 
15 LPFILETIME lpKernelTime, 

LPFILETIME IpUserTime 

); 

At a Glance Header file: . Winbase.h 
20 Module/component: 

Platforms: H/PC 



SUESTITUTE SHEET (RULE 26) 



WO 99/49394 PCT/US99/06223 

152 



Detailed Description of a Speech-to-Text API 
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CHAPTERS 
IVoiceText 

5 The IVoiceText interface registers an application to use the voice- 

text object, and controls playback of text. 

Method . Description - 

!VoiceText::AudioFastForward Unsupported 
10 IVoiceText::AudioPause Pauses text-to-speech output 

IVoiceText: :AudioResume Resumes text-to-speech 

output 

IVoiceText: :AudioRewind Unsupported 
!VoiceText::Register Registers an application to 

1 5 use voice text 

IVoiceText:: Speak Starts playing the specified 

text 

!VoiceText::StopSpeaking Halts text that is currently 



20 



being spoken 



IVoiceText::AudioPause 
25 Pauses text-to-speech output for a voice-text site. 

Syntax HRESULT AudioPause(void); 

Parameters None 

30 

Return Values This method returns NOERROR if successful, or one of these 
error values: 

VTXTERR_INV ALIDM ODE 
VTXTERR_NOTENABLED 
35 VTXTERRJ3UTOFMEM 

Remarks AudioPause affects all applications using the site, so the 
application should resume audio as soon as possible. 

40 When a voice-text object is first created, text-to-speech output is 

not paused. Because pausing text-to-speech output affects all 
applications that use voice text on the site, an application should 
resume text-to- speech output as soon as possible by calling the 
IVoiceText::AudioResume member function. 



45 



When output has been paused, the IVTxtAttributes::IsSpeaking 
member function returns FALSE, even though the voice-text 
object still has data available in its queue and has not yet sent a 
IVTxtNotifySink::SpeakingDone notification. 
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No notifications are sent when audio is paused or resumed. 

See Also IVoiceText::AudioResume, IVTxtAttributes::IsSpeaking, 
IVTxtNotifySink::SpeakingDone 



JVoiceText::AudioResume 

Resumes text-to-speech output after it has been paused by the 
IVoiceText::AudioPause member function. 

Syntax HRESULT AudioResume(void); 

Parameters None 



Return Values This method returns NOERROR if successful, or one of these 
error values: 

20 VTXTERR_INV ALIDM ODE 

VTXTERR_NOTENABLED 
VTXTERR OUTOFMEM 



Remarks AudioResume affects all applications, using the site. 
See Also IVoiceText::AudioPause 



30 lVoiceText::Register 

Registers an application to use voice text on a site. 

Syntax HRESULT Register ( 

35 PTSTR pszSite, 

PTSTR pszAppIication, 

PIVTXTNOTIFYSINK pNotifylnierface, 

1ID llDNorifylnterface, 

DWORD dwFlags, 
40 PVTSITEINFO pSiielnfo 

); 

Parameters pszSite 

For Auto PC, must be null or empty. 
45 pszApplicaiion 

[in] Address of a string that identifies the application - for 
example, "Microsoft Word." An application can use this 
information to display the source of text. This parameter 
must not be NULL. 
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pNotifylnterface 

[in] Address of the notification interface through which 
the voice-text object notifies the application about text-to- 
speech information. If this parameter is NULL, no 
notifications will be sent. The interface identifier is 
specified by IlDNoiifylnterface. 

Because passing the pointer to the voice-text object does 
not transfer ownership of the notification interface, the 
voice-text object must call the AddRef member function 
of the notification interface before returning from the call 
to Register. The voice-text object must also call the 
Release member function of the notification interface 
when it closes. The calling application must release any 
reference counts it holds on the notification interface after 
calling Register, unless it needs the notification object to 
be valid when the voice-text object releases it. 

HDNotijyJnterface 

[in] GUID of the interface used for notification. For Auto 
PC, this parameter must be IID^IVTxtNotifySinkW (for 
Unicode). ~ 

dwFlogs 

[in] Flag that indicates whether the application is to 
receive all notifications. If this parameter is the 
VTXTF_ALLMESSAGES value, all notifications are sent 
to pNotifylmerface. If this parameter is zero (0) or null, 
only the IVTxtNotifySink::SpeakingStarted and 
IVTxtNotifySink::SpeakingDone notifications are sent. 
pSitelnfo 

[in] Address of a VTS1TEINFO structure that contains 
settings to apply to the site, such as the voice and talking 
speed. The settings are applied, even if the site is already 
open. If a VTS1TEINFO structure is not specified, the 
voice-text object uses the settings from the registry. If 
there are no registry settings, it uses the default settings, 
typically those for the computer. 

Telephony applications pass this information to ensure 
that the proper settings are selected. Other applications 
will set this parameter to NULL to leave the site settings 
unchanged. 

Return Values This method returns NOERROR if successful, or one of these 
error values: 

VTXTERR_INVALJDPARAM 
• VTXTERRJDUTOFMEM 
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Remarks An application must call Register before it can call other 
functions in the IVoiceText interface. 

An application cannot call Register a second time for the same 
voice-text object. To change sites, the application must call the 
CoCreatelnstance function to create a new voice-text object for 
the desired site. 



See Also VTSITEJNFO, IVTxtNotif\'Sink::SpeakingStarted, 
1 0 IVTxtNotifySink:: Speaking Done 



IVoiceText::Speak 

15 Starts playing the specified text. 

Syntax HRESULT Speak( 

PTSTR pszSpeak, 
DWORD dwFlags, 
20 PTSTR pszTags 

); 

Parameters pszSpeak 

[in] Address of a buffer that contains the text to speak. An 
' 25 application can free or modify thebuffer as soon as Speak 

returns. The string pointed to by this parameter can 
contain text-to-speech control tags. 
dwFlags 

[in] Flags that indicate the type and priority of the text. 
30 This parameter is a combination of one type flag and one 

priority flag. 

The type flag can be one of these values: 
VTXTSPJilGH 

35 Play the text as soon as possible, after text that is 

currently being spoken but before any other text in 
the playback queue. 
VTXTSP_NORMAL 

Play the text immediately, interrupting text that is 

40 currently being spoken, if any. The intenrupted 

text resumes playing as soon as the very high 
priority text is finished, although the interrupted 
text may not be correctly synchronized. 

pszTags 

45 [in] Address of a buffer that contains text-to-speech 

control tags to change the voice, language, or context of 
the text specified by pszSpeak, or NULL to use the default 
settings for the text-to-speech voice. For more 
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15 



20 



information about control tags, see Appendix A, "Text-to- 
Speech Control Tags," 

Return Values This method returns NOERROR if successful, or one of these 



Remarks 



25 See Also 



error values: 



VTXTERR 

vtxterr" 
vtxterr] 

VTXTERR^ 
VTXTERR" 

vtxterr" 



INV AL1DM ODE 

INVALID? ARAM 

NOTENABLED 

OUTOFMEM 

QUEUEFULL 

WAVEDEVICEBUSY 



If an application calls Speak when other text is being played, the 
specified text is added to the end of the playback queue, unless 
the application specifies a higher priority in dwFIags. 

Calling Speak affects all applications using voice text on the site, 
because all applications share the same playback queue. 

The type of speech specified by dwFIag* is communicated to the 
text-to-speech engine through control tags. Suppon oi most 
control tags is optional; the engine ignores unsupported tags. 

IVoiceText::StopSpeaking 



30 



40 



45 



!VoiceText::StopSpeaking 



Halts text that is currently being spoken and flushes all pending 
text from the playback queue. 



Syntax HRESULT StopSpeaking(void); 

35 Parameters None 



Rerum Values This method returns NOERROR if successful, or one of these 
error values: 

VTXTERR JNVALIDMODE 
VTXTERR_NOTENABLED 
VTXTERR OUTOFMEM 



Remarks Calling StopSpeaking affects all applications using voice text on 
the site, because all applications share the same playback queue. 

See Also IVoiceText::Speak 
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IVTxtAttributes 



The IVTxtAttributes interface allows an application to control 
various aspects of the operation of a Voice Text object. 

Method Description , 

IVTxtAttributes: :DeviceGet Not Implemented 
IVTxtAttributes::DeviceSet Not Implemented 

IVTxtAttributes::EnabledGet Discovers whether voice text 

is enabled. 

IVTxtAttributes: :EnabledSet Enables or disables voice text. 
!VTxtAttributes::IsSpeaking Indicates whether text is 

currently being spoken. 
IVTxtAttributes: :SpeedGet Retrieves the current average 

talking speed. 

IVTxtAttributes::SpeedSet Sets the average talking 

speed. 

JVTxtAttributes::TTSModeGet Retrieves the current text-to- 
speech mode. 

TVTxtAttributes::TTSModeSet Sets the text-to-speech mode. 



JVTxtAttributes::EnabJedGet 

10 

Discovers whether voice text is enabled for a voice-text site. 

Syntax HRESULT EnabledGet( 

DWORD *dwEnabled 

15 ); 

Parameters dwEnabled 

[out] TRUE if voice text is enabled for the site or FALSE 
if it is disabled. 

20 

Return Values This method returns NOERROR if successful, or one of these 
error values: 

• VTXTERRJNVALEDMODE 

• VTXTERRJNVAL1DPARAM 
25 • VTXTERR_OUTOFMEM 

Remarks If voice text is disabled, no text-to-speech is played over the site. 

Enabling or disabling voice text for a site affects all applications 
using a voice-text site. 



30 



Typically, an application disables voice text because the user does 
not want the computer to speak. You should involve the user 
when enabling or disabling voice text. 



SUBSTITUTE SHEET (RULE 26) 



WO 99/49394 



PCTAJS99/06223 



159 



The enabled state for a site is saved between uses of the site, even 
if the user shuts down the computer in the meantime. 

5 See Also IVTxtAttributes::EnabledSet 

lVTxtArtributes::EnabledSet 

10 Enables or disables voice text for a voice-text site. 

Syntax HRESULT EnabledSet( 

DWORD dwEnabled 

); 

Parameters dwEnabled 

[in] TRUE to enable voice text or FALSE to disable it. 



15 



Return Values This method returns NOERROR if successful, or one of these 
20 error values: 

• VTXTERRJNV ALIDM ODE 

• ^^rXTER.R_INVALn??ARAM 
VTXTERRJ3UTOFMEM 

25 Remarks The enabled state for a site is saved between uses of the site, even 
if the user shuts down the computer in the meantime. 

Jf a voice-navigation application is installed on the user's 
computer, an application may not need to set the enabled state. 



30 



35 



See Also IVTxtAttributes::EnabledGet 



IVTxlAttributes::IsSpeaking 

Indicates whether text is currently being spoken by a voice-text 
site. 



Syntax HRESULT IsSpeaking( 

40 BOOL *pfSpeaking 

); 

Parameters pfSpeaking 

[out] Address of a variable that receives the current 
45 speaking status. The variable receives TRUE if the text- 

to-speech engine is speaking or FALSE if it is silent. 

Return Values This method returns NOERROR if successful, or one of these 
error values: 
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• VTXTERRJNVALIDMODE 

• VTXTERRJNVALIDPARAM 
VTXTERR_OUTOFMEM 

The voice text object does not send data resulting from multiple 
calls to the IVoiceText::Speak member function directly to thej 
text-to-speech engine. Instead, the object keeps data from each 
call in a separate buffer so that the VTXTSP_H1GH and 
VTXTSPJVERYH1GH priority strings can be inserted into the 
queue at the proper positions. 

For example, a VTXTSPJVERYH1GH priority string may 
interrupt a high or normal priority string. The interrupted string 
resumes after the very high priority string has finished. As a 
1 5 result of this implementation, IsSpeaking returns FALSE for a 

short time between the end of one buffer in the queue and the start 
of the next buffer, because audio output has been temporarily 
suspended. 

20 

IVTxtAttributes::SpeedGet 

Retrieves the current average talking speed for a voice-text she, in 
words per minute. 

HRESULT SpeedGet( 

DWORD *pdwSpeed 

); 



5 Remarks 



10 



25 

Syntax 



30 Parameters pdwSpeed 

[out] Address of a variable that receives the talking speed 
for a voice-text site. 

Return Values This method returns NOERROR if successful, or one of these 
35 error values: 

• VTXTERRJNVALIDMODE 

• VTXTERR_INVALIDPARAM 

• VTXTERRJDUTOFMEM 

40 Remarks The talking speed for a site is saved between uses of the site, even 
if the user shuts down the computer in the meantime. 

See Also IVTxtAttributes::SpeedSet 

45 
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]VTxtAt(nbutes::SpeedSet 

Sets the average talking speed for a voice-text site, in words per 
minute. 

5 

Syntax HRESULT SpeedSet( 

DWORD dwSpeed 

); 

10 Parameters dwSpeed 

[in] New talking speed for the site. An application can 
specify TTSATTRJvJINSPEED or 
TTSATTRJvl AX SPEED for the minimum or maximum 
allowable value. 

15 

Return Values This method returns NOERROR if successful, or one of these 
error values: 

VTXTERRJNVALIDMODE 
VTXTERRJNVALIDPARAM 
20 • VTXTERRJDUTOFMEM 

Remarks The talking speed for a site is saved b<:tv--e?n uses of the site, cv±u 
iftne user shuts down the computer in the meantime. 

25 If a voice-navigation application is installed on the user's 

computer, an application may not need to set the speed. 



30 



35 



See Also !VTxtAttributes::SpeedGet 



]VTxtAttributes::TTSModeGet 



Retrieves the GUID of the current text-to-speech mode for a 
voice-text site. 



Syntax HRESULT TTSModeGet( 

GUID *pg Voice 

); 

40 Parameters pg Voice 

[out] Address of a variable that receives the GUID 
assigned to the text-to-speech mode. 

Return Values This method returns NOERROR if successful, or one of these 
45 error values: 

VTXTERR_INVALlDMODE 
VTXTERRJNVALIDPARAM 
VTXTERR OUTOFMEM 
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Remarks A text-to-speech engine typically provides an assortment of text- 
to-speech modes that can be used to play speech in different 
voices. A voice-text site uses a single text- to- speech mode, 
5 represented internally by a low-level engine object. 

The text-to-speech mode for a site is saved between uses of tlje 
site, even if the user shuts down the computer in the meantime. 

10 In Auto PC, there is usually only one TTS mode. 

See Also IVTxtAttributes::TTSModeSet 

15 IVTxtAttributes::TTSModeSet 

Sets the text-to-speech mode for a voice-text site. 

Syntax HRESULT TTSModeSet( 

20 GUID g Voice 

); 

"" ' " Parameters g Voice 

[in] GUID of the text-to-speech mode to set for the site. If 
25 the mode does not exist, an error is returned and the mode 

is not changed. 

Return Values This method returns NOERROR if successful, or one of these 
error values: 

30 • VTXTERRJNVALIDMODE 

VTXTERR_INVALEDPARAM 
VTXTERRJDUTOFMEM 

Remarks The text-to-speech mode for a site is saved between uses of the 
35 site, even if the user shuts down the computer in the meantime. 

If a voice-navigation application is installed on the user's 
computer, an application may not need to set the mode. 

40 In Auto PC, there is usually only one TTS mode. 

See Also IVTxtAttributes::TTSModeGet 



45 IVTxtNotifySink 



The IVTxtNotifySink interface is used by a Voice Text object to 
notify an application of the status of the object. 
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Method Description 

rVTextNotifySink::AuribChanged Not implemented 
IVTextNotifySink::Speak Used internally 

IVTxtNotifySink::SpeakingDone Speaking is finished 
IVTxtNotifySink::SpeakingStarted Speaking has started 
rVH>xtNotifySink::Visual , Not Implemented 



nTxtNotifySink::SpeakingDone 

5 

Notifies all applications on a voice-text site that speaking is 
finished and no text remains in the playback queue. 

Syntax HRESULT SpeakingDone (void); 

10 

Parameters None 

Return Values The return value is ignored. 
15 See Also IVTxtNotifySink::SpeakingStarted 



I\TxtiNotifySink::SpeakjrgStarled 

20 Notifies all applications on a voice-text site that speaking has 

started. 

Syntax HRESULT SpeakingStarted(void); 

25 Parameters None 

Return Values The return value is ignored. 

See Also IVTxtNotifySink::SpeakingDone 
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Chapter 4 
IVCmdAttributes 

5 The IVCmdAttributes interface provides methods to set various 

attributes of the Voice Command object, including audio output, 
recognition mode, and whether or not recognition is enabled. * 



Method 



IVCmdAuributes::AutoGainEnable 
Get 

IVCmdAttributes::AutoGainEnable 
Set 

IVCmdAttributes::AwakeStateGet 

IVCmdAttributes::AwakeStateSet 

IVCmdAttributes::DeviceGet 
IVCmdAttributes: :DeviceSet 
IVCmdAttributes: :EnabledGet 



IVCmdAttributes: :EnabledSet 



IVCmdAttributes::MicrophoneGet 
IVCmdAttributes::MicrophoneSet 
IVCmdAttributes ::SpeakerGet 



IVCmdAttributes: :SpeakerSet 



IVCmdAttributes::SRModeGet 



IVCmdAttributes: :SRModeSet 



IVCmdAttributes::ThresholdGet 



Description 



Not Implemented 

Not Implemented 

Retrieves the awake state 
of a voice-command site. 
Sets the awake state for a 
voice-command site. 
Not Implemented 
Not Implemented 
Finds out whether speech 
recognition h enabled or 
disabled for a voice- 
command site. 
Enables or disables speech 
recognition for a voice- 
command site. 
Not Implemented 
Not Implemented 
Retrieves the name of the 
current speaker for a voice- 
command site. 
Sets the name of the 
current speaker for a voice- 
command site. 
Retrieves the GUID of the 
speech-recognition mode 
used for the site. 
Sets the speech-recognition 
mode used by a voice- 
command site. 
Retrieves the threshold 
level of the speech- 
recognition engine used by 
a voice-command site. 
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Method 


Description 


lVCmdAttributes::ThresholdSet 


Sets the threshold level for 




the speech-recognition 




engine used by a voice- 




command site. 



Remarks This interface is supported by all voice-command objects. 

5 

]VCmdAttributes::AwakeStateGet 

IVCmdAttributes::AwakeStateGet retrieves the awake state for a 
voice-command site. 

10 

Syntax HRESULT AwakeStateGet( 

DWORD *pdwAwake 

); 

1 5 Parameters pdwAwake 

[out] Address of a variable that receives the current state 
. of speech jecogni-fioi: "oEJhc-s:tc. Thic p: ; rif^ie: \& 
TRUE if the site is r.wuke or FALSE if it is as jeep. 

20 Return Values This method returns NOERROR if successful, or one of these 
error values: 

• EJNVAL1DARG 

VCMDERRJNVALIDMODE 
VCMDERRJDUTOFMEM 
25 • VCMDERR_VALUEOUTOFRANGE 

Remarks When the site is awake, it listens for commands from any active 
voice menu for the active application. When the site is asleep, it 
listens for commands only from sleep menus - those that were 

30 activated with the dwFlags parameter of the 

JVCmdMenu::Activate member function set to the 
VWGFLAG_ASLEEP value. Commands from such menus 
become active only when the site is asleep, and they become 
inactive when the site is awake. A sleep menu typically contains 

35 a "Wake up!" command that resumes speech recognition, and it 

may contain other commands. 

See Also IVCmdAttributes::AwakeStateSet 

40 
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]VCmdAttributes::A>vakeStateSet 

I VCmd Attributes:: AwakeStateSet sets the awake state for a 
voice-command site. 

5 

Syntax HRESULT AwakeStateSet( 

DWORD dwAwake 

); 

] 0 Parameters dwAwake 

[in] Set to TRUE to cause the site to wake up or FALSE to 
cause it to go to sleep. 

Return Values This method returns NOERROR if successftil, or one of these 
15 error values: 

• EJNVALIDARG 

• VCMDERR JNV ALIDM ODE 

• VCMDERR_OUTOFMEM 
VCMDERR_VALUEOUTOFRANGE 

Remarks If a voice-navigation application is installed on the -user's 

- ' - computer,, ^i^pendin-^speicr? reso£ni??on by ■ ' • ~ ' 

AwakeStateSet will typically cause the voice-navi^ ation 
application to activate a "wake un" menu. 

25 - 

Calling AwakeStateSet allows the user to temporarily suspend 
speech recognition for a site. For example, the user might want to 
suspend speech recognition from the computer microphone 
during a telephone conversation and resume recognition when the 
30 conversation is finished. The user resumes recognition by 

speaking an appropriate command from a sleep menu - for 
example, "Wake up!" 

The sleep state for a site is saved between uses of the site, even if 
35 the user shuts down the computer in the meantime. 

If a voice-navigation application is installed on the user's 
computer, an application may not need to set the sleep state. 
However, it may call this function to make sure that speech 
40 recognition is awake. For example, if an application speaks (with 

voice text or text-to-speech) "Do you want to print the 
document?" it might enable and wake up speech recognition for 
the site to receive the user's reply. The application should then 
restore speech recognition to its previous state. 

45 
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]VCmdAttributes::EnabledGet 

IVCmdAttributesnEnabledGet finds out whether speech 
recognition is enabled or disabled for a voice-command site. 

5 

Syntax HRESULT EnabledGet( 

DWORD *dwEnab!ed 

); 

10 Parameters dwEnabled 

[out] Set to TRUE if speech recognition is enabled for the 
site or FALSE if it is disabled. 

Return Values This method returns NOERROR if successful, or one of these 
1 5 error values: 

• EJNVALIDARG 

• VCMDERRJNVAL1DMODE 

• VCMDERR_OUTOFMEM 
VCMDERR_VALUEOUTOFRANGE 

20 

Remarks When speech recognition is disabled, the engine does not 
;. -•"::{;: recognize .^v-com:niaVd^onva^y inenu, whether sp^ch" ' 11 
recognition is awake or asleep ox any menus are active. An 
application would use the IVCmdAttnbutes::EnabledSet member 
25 function to allow the user to turn speech recognition completely 

off, as opposed to suspending speech recognition temporarily by 
putting the site to sleep. 

The enabled state for a site is saved between uses of the site, even 
30 if the user shuts down the computer in the meantime. 



]VCmdAttributes::EnabIedSet 

35 IVCmdAttributes::Enab]edSet enables or disables speech 

recognition for a voice-command site. 

Syntax HRESULT EnabledSet( 

DWORD dwEnabled 

40 ); 

Parameters dwEnabled 

[in] Set to TRUE to enable speech recognition or FALSE 



45 



to disable it. 

Return Values This method returns NOERROR if successful, or one of these 
error values: 

E INVALIDARG 
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• VCMDERRJNVALIDMODE 

• VCMDERRJDUTOFMEM 

• VCMDERR_VALUEOUTOFRANGE 

5 Remarks Whenever speech is turned on or off, the 

WMSPEECHSTARTED or WM_SPEECHENDED message is 
sent to all top-level windows in the system. An application can 
use these messages to determine when to enable or disable its 
voice commands or voice-text capabilities. 

Calling EnabledSet allows the user to completely turn off speech 
recognition for a site so that nothing is recognized, including 
commands on sleep menus. For example, the user might want to 
disable speech recognition from the computer microphone during 
a meeting so that speech recognition will stay off, even if 
somebody inadvertently speaks a command on a sleep menu. 

If a voice-navigation application is installed on the user's 
computer, an application may not need to set the enabled state. 
However, it may call this function to make sure that speech 
recognition is awake. For example, if an application speaks (vi'tfc 

yoke^t or texl.-to--spp.tfch) "Do you-riv^m to pri^t/ihe;- " \ : /^r^; 
document?" it might enable and wake up speech -recognition for 
the site to receive the user's reply. The application should then 
restore speech recognition to its previous state. 

Note, however that, if speech recognition is disabled, it is 
probably because the user does not want to use it. It may not be 
appropriate to enable speech recognition under those 
30 circumstances. 

The enabled state for a site is saved between uses of the site, even 
if the user shuts down the computer in the meantime. 

35 

IVCmdAttributes::SpeakerGet 

R'CmdAttributes::SpeakerGet retrieves the name of the current 
speaker for a voice-command site. 

40 

Syntax HRESULT SpeakerGet( 

PTSTR pszSpeaker, 
DWORD dwSize, 
DWORD *pdxvNeeded 

45 ); 

Parameters pszSpeaker 

[in/out] Address of a buffer that receives the name of the 
current speaker. 
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dwSize 

[in] Size, in bytes, of the buffer specified by pszSpeaker. 
If the buffer is too small, the function returns an error and 
fills pdwNeeded with the number of bytes needed to store 
5 the speaker string. 

pdwNeeded r 
[out] Address of a variable that receives the number of 
bytes needed for the speaker string. 

1 0 Return Values This method returns NOERROR if successful, or one of these 
error values: 

EJNVALIDARG 
• VCMDERRJNVALIDMODE 
VCMDERR_NOTSUPPORTED 
15 • VCMDERR_OUTOFMEM 

VCMDERR^VALUEOUTOFRANGE 

Remarks Changing the speaker name unloads all training for the previous 
speaker and loads the training for the new speaker. If no training 
20 exists for the new speaker, the application starts with default 

■ v. ; training. ■■•.,.*;_.:;. ... \ -.•--••-:.:{v-/> »- "v-» . ~-> : ^ 'v 



25 



35 



40 



45 



The speaker name for a site is. saved between uses of th;^ site, 
even if the user shuts down the compute? in the meantime. 



IVCmdAt1ributes::SpeakerSet 



IVCmdAttributes::SpeakerSet sets the name of the current 
30 speaker for a voice-command site. 

Syntax HRESULT SpeakerSet( 

PTSTR pszSpeaker 

); 



Parameters pszSpeaker 

[in] Address of the string that contains the name of the 
speaker to set. If the speaker is unknown, this parameter 
can be an empty string. 

Return Values This method returns NOERROR if successful, or one of these 
error values: 

E_INVAL1DARG 
VCMDERR_INVALIDMODE 
VCMDERR_NOTSUPPORTED 
VCMDERR_OUTOFMEM 
VCMDERR VALUE OUTOF RANGE 
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40 



45 



Remarks The speaker name for a site is saved between uses of the site, 
even if the user shuts down the computer in the meantime. The 
string is not case sensitive. 

]f a voice-navigation application is installed on the user's 
computer, an application may not need to set the speaker name 



IVCmdAltributes::SRModeGet 

]VCmdAttributes::SRModeGet retrieves the GUID of the speech- 
recognition mode used for the site. 



Syntax HRESULT SRModeGet( 

15 GUID*pgMode 

); 

Parameters pgMode 

[out] Address of a variable that receives the unique GUID 
20 assigned to the speech-recognition mode. 

Return Values This method; reiurn^^Q^I^ORJf succ^-f ?1, oi one *f -hese 
error values: 

• . E_ INVALID ARG 

25 • VCMDERR^I^-AiiDMODE 

• VCMDERR_NOTSUPPORTED 
VCMDERR_OUTOFMEM 

Remarks A speech-recognition engine typically provides an assortment of 
30 modes that it can use to recognize speech in different languages or 

dialects. A voice-command site uses a single speech-recognition 
mode. 

The speech-recognition mode for a site is saved between uses of 
35 the site, even if the user shuts down the computer in the 

meantime. 



In Auto PC, there is usually only one speech recognition mode. 



IVCmdAttributes::SRModeSet 



R ; CmdAttributes::SRModeSet sets the speech-recognition mode 
used by a voice-command site. 



Syntax HRESULT SRModeSet( 

GUID gMode 

); 
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Parameters gMode 

[in] GULD of the speech-recognition mode to set for the 
site. If the mode does not exist, an error is returned and 
5 the mode is not changed. 

Return Values This method returns NOERKOR if successful, or one of these 
error values: 

EJNVALIDARG 
10 • VCMDERRJNVAJJDMODE 

• VCMDERRJvIOTSUPPORTED 
VCMDERR_OUTOFMEM 
VCMDERR_VALUEOUTOFRANGE 



20 



25 



15 Remarks 



The speech-recognition mode for a site is saved between uses of 
the site, even if the user shuts down the computer in the 
meantime. If a voice-navigation application is installed on the 
user's computer, an application may not need to set the speech- 
recognition mode. 

An application can use a speech-recognition enumerator to 
'detenrjVc whfe^ available. For 

information about the speech-recognition enumerator, see the 
section, "Speech Recognition." 

In Auto PC, there is usually only one speech recognition mode. 



30 



IVCmdAttribules::TbresboldGet 



IVCmdAttributes::'ThresholdGet retrieves the threshold level of 
the speech-recognition engine used by a voice-command site. 



Syntax HRESULT ThresholdGet( 

35 DWORD *pdwThreshold 

); 

Parameters pdwThreshold 

[out] Address of a variable that receives the threshold 
40 level. 



Return Values This method returns NOEJtROR if successful, or one of these 
error values: 

EJNVALIDARG 

45 • VCMDERR_INV ALIDM ODE 

• VCMDERRJsfOTSUPPORTED 

• VCMDERR_OUTOFMEM 
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Remarks The threshold level is a value from 0 to 100 that indicates the 

point below which an engine rejects an utterance as unrecognized. 
A value of 0 indicates that the engine should match any utterance 
to the closest phrase match. A value of 100 indicates that the 
5 engine should be absolutely certain that an utterance is the 

recognized phrase. For example, suppose the engine is expecting 
"What is the time?" If the threshold is 1 00 and the user mumbles 
"What'z tha time" or has a cold, the command may not be 
recognized. However, if the threshold is too low and the user 
1 0 *£ys a similar-sounding phrase that is not being listened for such 

as "What is mine?" the engine may recognize it as "What is the 
time?" 

If the command spoken by the user is not close enough to what 
1 5 the speech-recognition engine expects, the voice-command object 

notifies the application that the command was not recognized by 
calling IVCmdNotifySink::CommandOther with a NULL phrase. 

The threshold for a site is saved between uses of the site, even if 
20 the user shuts down the computer in the meantime. 

25 IVCmdAttributes::Thieshc]dSet sets ihe threshold level for the 

speech-recognition engine used by a voice-command site. 

Syntax HRESULT ThreshoIdSet( 

DWORD dwThreshold 

30 ); 

dwThreshold 

[in] Threshold level. An application can specify 
SRATTR_MINTHRESHOLD and 
SRATTR_MAX THRESHOLD for minimum and 
maximum allowable values. 



Parameters 

35 



Return Values This method returns NOERROR if successful, or one of these 
error values: 
40 • EJNVALIDARG 

• VCMDERR_INVALIDMODE 

• VCMDERJR_NOTSUPPORTED 

• VCMDERR_OUTOFMEM 
VCMDERR VALUEOUTOFRANGE 

45 

Remarks The threshold level is a value from 0 to 1 00 that indicates the 
point below which an utterance is rejected as unrecognized. A 
threshold level of 0 indicates that the engine should match any 
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utterance to the closest phrase match. A value of 100 indicates 
that the engine should be absolutely certain that an utterance is 
the recognized phrase. If the value is out of range for the engine, 
an error is returned and the attribute is not changed. 

The threshold for a site is saved between uses of the site, ev^n if 
the user shuts down the computer in the meantime. 

If a voice-navigation application is installed on the user's 
1 0 computer, an application may not need to set the threshold. 



JVCmdEnum 

15 The IVCmdEnum interface is a standard OLE enumeration 

interface. It is used by applications to enumerate the menus 
stored in the voice-command database. 



Method ; Description 



20 



25 



]VCmdEnum::Clone Retrieves another enumerator 

containing the same enumeration 
... : .staters the currc:.: :»ic: . . . _ 

IVCmdEnum:.Ne:xt. Retrieves the specified number of 

items in the enumeration sequence. 
IVOmdEnum::Reset Resets the enumeration sequence 

back to the beginning. 
IVCmdEnum::Skip Skips over a specified number of 

elements in the enumeration 
sequence. 



Remarks This interface is supported by all voice-command objects. 



IVCmdEnum::Clone 

IVCmdEnum::Clone retrieves another enumerator containing the 
same enumeration state as the current one. 



Syntax HRESULT Clone( 

30 IEnumX **ppenum 

); 

Parameters ppenum 

[out] Address of a variable that receives the cloned 
35 enumerator. The type of this parameter is the same as the 

enumerator name. For example, if the enumerator name is 
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IEnumFORMATETC, this parameter is of the 
IEnumFORMATETC type. 

Return Values This method returns NOERROR if successful, or one of these 
5 error values: 



EJNVALIDARG 
E_OUTOFMEMORY 
• E_UNEXPECTED 

10 Remarks Using Clone, it is possible to record a particular point in the 

enumeration sequence and then return to that point at a later time. 
The enumerator returned is of the same interface type as the one 
being cloned. 

15 

]VCmdEnum::Next 

IVCmdEnum::Next retrieves the specified number of items in the 
enumeration sequence. 

20 

Syntax HRESULT IEnumX::Next( 

- . -V ULONGc*/*, . - ;".„.,. ,\- 

Unknown **rgeii, 
ULONG *pceltFeiched 

25 ); . 

Parameters celt 

[in] Number of elements to retrieve. If the number of 
elements requested is more than remains in the sequence, 
30 only the remaining elements are retrieved. 

rgelt 

[out] Address of an array that receives the elements. If an 
error value is returned, no entries in the array are valid. 
pceltFetched 

35 I°ut] Address of a variable that receives the number of 

array elements actually copied to the array. This 
parameter cannot be NULL if celt is greater than one. If 
this parameter is NULL, celt must be one. 

40 Return Values This method returns NOERROR if successful, or one of these 
error values: 

EJNVALIDARG 
E_OUTOFMEM ORY 
E^UNEXPECTED 
45 • S_FALSE 

S OK 
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]VCmdEnum::Reset 

IVCmdEnum "Reset resets the enumeration sequence back to the 
beginning. 

5 

Syntax HRESULT IEnumX::Reset(void); 

Parameters None 

1 0 Return Values This method returns NOERROR if successful, or one of these 
error values: 

S_FALSE 
S_OK 

IVCmdEnum::Skip 

IVCmdEnum::Skip skips over a specified number of elements in 
the enumeration sequence. 

HRESULT IEnumX::Skip ( 

; v..mONG^- -,. 

25 Parameters celt 

[in] Number of elements to be skipped. 

Return Values This method returns NOERROR if successful, or one of these 
error values: 
30 • EJNVALIDARG 

E_OUTOFMEMORY 
• EJJNEXPECTED 
S_FALSE 
S_OK 

35 

IVCmdMenu 

The IVCmdMenu interface allows an application to manage 
40 voice-command menus. It includes methods for such tasks as 

activating and deactivating menus, and adding and deleting 
phrases. 



Method 


Description 


I VCmdM enu : : A cti vate 


Activates a voice menu so that its 


JVCmdMenu::Add 


commands can be recognized. 


Adds one or more commands to a 




voice menu. 



20 

Syntax 
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Method 

IVCmdMenu: :Deactivate 
IVCmdMenu::EnableItem 

IVCmdMenu::Get 

IVCmdMenu::ListGet 

IVCmdMenu::ListSet 

IVCmdM enu : :Num 

JVCmdMenu::Remove 

IVCmdMenu::Set 

]VCmdMenu::SetItem 

IVCmdMenu::TrainMenu 
Dig 



Description 



Deactivates an active voice menu. 
Permanently enables or disables a 
menu item. 

Retrieves information about one or 
more commands in a voice menu. 
Retrieves the phrases stored in the 
current list for the selected voice 
menu. 

Sets the phrases in a list for a voice 
command. 

Retrieves the total number of 
commands on a voice menu. 
Removes the specified commands 
from the voice menu. 
Sets information for one or more 
commands in a voice menu. 
Temporarily enables or disables a 
command on a voice menu. 
Not Implemented 



The following flags are used with the member func-ions of the 
IVCmdMenu interface to identify a command in a voice- 
5 command menu: 

VCMD_BY_IDENTIFIER 

The dwCmdNum is the command identifier of the 
command. 
VCMDJ3Y_POSIT10N 
1 0 The dwCmdNum parameter is the position in the list of 

commands. 

Remarks This interface is supported by all voice-command objects. 

15 

IVCmdMenu:: Activate 

IVCmdMenu::Activate activates a voice menu so that its 
commands can be recognized. 

20 

Syntax HRESULT Activate( 

H WND h WndListening, 
DWORD dwFIags 

); 

25 
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Parameters hWndListening 

[in] Handle of the window associated with the voice 
menu. Whenever this window is the foreground window, 
the voice menu is automatically activated. Otherwise, it is 
5 deactivated. If this parameter is NULL, the voice menu is 

global (that is, it remains active regardless of the 
foreground window, until the application explicitly 
deactivates it). 

10 Note: For the AutoPC, set this parameter to NULL. The 

application has to activate and deactivate the voice menu 
manually when the focus switches. 
dwFlags 

[in] Flag that indicates whether the menu should be active 
1 5 when speech-recognition is "asleep" for the voice- 

command site. This parameter can be one of these values: 
Oor NULL 

The voice menu is active only when speech 
recognition is awake. 
20 VWGFLAG_ASLEEP 

The menu is active only when speech recognition 
is asleep and is autGr;:*vr-aIJ"v deactivucd u VSyr 
speech recognkioa awake. 
Most applications set this parameter to zero, Typically, a sleep 
25 menu contains a command to resume speech recognition, such as 

"Wake up." 

Return Values This method returns NOERROR if successful, or one of these 
error values: 
30 • EJNVALIDARG 

VCMDERR_CANTCREATEDATASTRUCTURES 
VCM DERR_C AN TIN! TD A T A S TRU CTURES 
VCMDERR_CANTXTRACTWORDS 
VCMDERR_INVALlD\VINDOW 
35 • VCMDERRJV1ENUACTIVE 

VCMDERR^MENUTOOCOMPLEX 
VCMD ERR_M ENUWR ON GL ANGU A GE 
VCMDERR_NOCACHEDATA 
VCMDERR_NOENGINE 
40 • VCMDERR^NOGRAMMARJNTERFACE 

V CMDERR_OUTOFMEM 
VCMDERRJ~00MAN^1ENUS 



45 



Remarks A global voice menu is useful for an application such as a clock 
program so that the user can ask what time it is and get a response 
no matter what else he or she is doing. Global voice-menu 
commands have a lower priority in case of a recognition conflict 
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- for example, two commands with the same name in different 
menus. 



]VCmdMenu;:Add 



IVCmdMenu::Add adds one or more commands to a voice njenu. 
The added commands are appended to any existing commands in 
the menu. 

10 

Syntax HRESULT Add( 

DWORD dwCmdNum, 
SDATA dData, 
DWORD *pdwCmdStart 

15 ); 

Parameters dwCmdNum 

[in] Number of commands to add to the menu. 

dData 

20 [in] SDATA structure containing a list of 

VCMDCOMMAND structures that describe the voice 
■ to be added,-- Although they van^ in si^ 1 

depending on the cottimard data, the structures are 

contiguous within the list. 
25 ' * pdwCr.tdSte.y-! 

[out] Address of a variable that receives the number of the 

first command added to the menu. 

Return Values This method returns NOERROR if successful, or one of these 
30 error values: 

EJNVAL1DARG 
VCMDERRJNVALIDCHAR 
VCMDERR_MENUTOOCOMPLEX 
• VCMDERR_OUTOFMEM 
35 • VCMDERRJVALUEOUTOFRANGE 

Remarks In Auto PC, applications should use the 

]APCSpeech::AddVMenuCommand function in the APC speech 
interface instead. 

40 

Commands are numbered sequentially from 1 to n. New 
commands are added to the end of the menu, so the first 
command added is numbered w+1. 

45 For best results, you should deactivate the voice menu before 

calling Add. Otherwise, the menu must be deactivated, 
recompiled, and reactivated before Add returns. If the menu is 
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already deactivated when Add is called, the menu is not 
recompiled until the application activates it again. 

If a command string includes a list name, you can use 
IVCmdMenu::ListSet to set the phrases that the user can 
substitute for the list name when speaking the command. 



10 



15 



20 



25 



30 



35 



40 



45 



]VCmdMenu::Deactivate 

JVCmdMenu::Deactivate deactivates an active voice menu so that 
the application no longer listens for its commands. 

Syntax HRESULT Deactivate(void); 

Parameters None 

Return Values This method returns NOERROR if successful, or 

VCMDERR_OUTOFMEM if a low memory condition exists. 

Remarks The menu is still open, so the application can start listening for 

V- v : . , v ™enu;.s.,commands again by calling IVGmdMenu::Ai;h\;.te toi 
reactive the menu. 

IVCmdMenu::Enable]tem 

IVCmdMenu::EnableItem permanently enables or disables a 
menu item. When a command is disabled by using Enableltem, it 
is not compiled into the menu. 

Syntax HRESULT Enableltem( 

DWORD dwEnable, 
DWORD dwCmdNum, 
DWORD dwFlag 

); 

Parameters dwEnable 

[in] TRUE to enable the command, or FALSE to disable 
it. 

dwCmdNum 

[in] Position or identifier of the command on the menu, 
depending on the value of dwFlag. Command positions 
are sequential, starting with 1 for the first command on the 
menu. The command identifier is specified in the dwID 
member of the VCMDCOMMAND structure that defines 
the command. 
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dwFlag 

[in] Flag that identifies the nature of dwCmdNum. This 
parameter can be one of these values: 
• VCMD_BYJDENT1FIER 
5 • VCMD_BY_POSITION 

Return Values This method returns NOERROR if successful, or one of these 
error values: 

• E_INVALIDARG 
10 • VCMDERRJDUTOFMEM 

Remarks For best results, you should deactivate the voice menu before 
calling Enableltem. Otherwise, the menu must be deactivated, 
recompiled, and reactivated before the function returns. If the 
1 5 menu is already deactivated when Enableltem is called, the menu 

is not recompiled until the application activates it again. 



IVCmdMenu::Get 

20 

IVCmdMenu::Get retrieves information about one or more 
. commands m a voicfcmei^u. - ''■•vi'y='v. - 

Syntax HRESULT Get ( 

25 DWORD dwCmdStart, 

DWORD dwCmdNum, 
DWORD dwFlag, 
PSDATA pdData, 
DWORD *pdwCmdNum 

30 ); 

Parameters dwCmdStart 

[in] Number of the first command to retrieve. Commands 
are numbered sequentially from 1 to n. UdwFIag is the 
35 VCMDJ3YJDENTIFIER value, this parameter is 

ignored. 
dwCmdNum 

[in] Either the number of commands to retrieve or 
the identifier of the commands, depending on the value of 
40 dwFlag. If the sum of dwCmdStart and dwCmdNum 

exceeds the total number of commands in the menu, the 
function returns as many commands as possible. 

dwFlag 

[in] Flag that identifies the nature of dwCmdNum. 
45 This parameter can be one of these values: 

VCMD_BY_IDENTIFIER 
VCMD BY POSITION 



SUBSTITUTE SHEET (RULE 26) 



WO 99/49394 



PCT/US99/06223 



182 



10 



15 



20 



pdData 

[out] Address of an SDATA structure that receives 
the address and size of a buffer. The buffer contains a list 
of VCMDCOMM AND structures that describe the 
commands retrieved. Although they vary in size 
depending on the command data, the structures are 
contiguous within the list. 
pdwCmdNum 

[out] Address of a variable that receives the number of 
commands actually copied to the buffer. 

Return Values This method returns NOERROR if successful, or one of these 
error values: 

• EJNVALIDARG 

• VCMDERRJNVALIDCHAR 
VCMDERR_MENUTOOCOMPLEX 

• VCMDERRJDUTOFDISK 
VCMDERRJDUTOFMEM 
VCMDERR_VALUEOUTOFRANGE 



Remarks 



25 



30 



The calling application allocate? the SDATA str ucture and 'wssw. 
its address to G<i. s Gi?fd":I;x roeinoiy (orfi g'the GUi task - 
allocator) for the returned data and sets the pData member of 
SDATA to point to the memory, If the aJlQCritiorriails, pDatnis 
sent to NULL and the dwSi2e member is set to zero. The calling 
application must free the memory pointed to by pData as well as 
the SDATA structure itself. 

The calling application must free the memory allocated by the 
member function by using the CoTaskMemFree function. 



]VCmdMenu::ListGet 



35 



IVCmdMenu::ListGet retrieves the phrases stored in the current 
list for the selected voice menu. 



Syntax HRESULT ListGet( 

PTSTR pszList, 
40 PSDATA pdLisU 

DWORD *pdwListNum 

); 



Parameters pszList 

[in] Name of the list, such as "name" or "weekday " The 
list name must appear in the command string for at least 
one command on the menu. The command string is stored 
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in the dwCommand member of the VCMDCOMM AND 
structure that defines the command. 

pdList 

[out] Address of an SDATA structure that receives the 
5 address and size of a buffer. The buffer contains a 

sequential list of null-terminated strings, one for each 
phrase in the list. 
pdwListNum 

[out] Address of a variable that receives the number of 
10 phrases that were copied to the buffer. If the list is empty, 

this parameter receives zero. 

Return Values This method returns NOERROR if successful, or one of these 
error values: 
15 • EJNVALIDARG 

VCMDERRJNVALIDLIST 
• VCMDERR_OUTOFMEM 

Remarks A list is associated with a menu rather than an individual 
20 command. The list must appear in at least one command string, 

.but c.an : be ; used .by more^han one comriano on ih^ : memu . . 

The calling application allocates the SDATA- structure and passes 
its addresr to ListGet. L;s:tltH allocates msmpry (using the OLE 
25 task allocator) for the returned data and sets the pData member of 

the SDATA structure to point to the memory. If the allocation 
fails, the pData member is set to NULL and the dwSize member 
is set to zero. The calling application must free the memory 
pointed to by pData, as well as the SDATA structure itself. 

30 

It is up to the calling application to free the memory allocated by 
the member function by using the CoTaskMemFree function. 

35 JVCmdMenu::ListSet 

IVCmdMenunListSet sets the phrases in a list for a voice 
command. 

H RESULT ListSet( 

PTSTR pszList, 
DWORD dwLisiNum, 
SDATA dList 

); 

pszList 

[in] Address of the name of the list to set, such as "name" 
or "weekday." The list name must appear in the command 
string for at least one command on the menu. The 
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10 



Returns 



15 



Remarks 



20 



25 



30 



35 



40 



command string is specified in the dwCommand member 
of the VCMDCOMMAND structure that defines the 
command. 
dwListNum 

[in] Number of phrases in the list. 

dList 

[in] SDATA structure that contains a pointer to a data ' 
buffer and the size of the buffer. The data buffer contains 
a sequential list of null-terminated strings, one for each 
phrase in the list. 

This method returns NOERROR if successful, or one of these 
error values: 

• EJNVALIDARG 

• V CM DERRJNV AL1D CHAR 
VCMDERR_INVAL1DLIST 
VCMDERR_OUTOFMEM 

The user can speak any phrase in the list in place of the list name 
in the command string. A command that uses a list must have the 
list name in brackets. Example: 

"Send mail to <name>" 

Calling ListSet establishes a list of phrases that can be spoken in a 
voice command, such as "Send mail to name." Typically, the list 
contains information that changes dynamically at run time, such 
as the ten people to whom the user most recently sent electronic 
mail. For best results, a list should have fewer than 20 entries. 
Having more than 20 entries in a list can reduce the accuracy of 
recognition. 

The list persists until the voice-menu object is released. List 
entries are not automatically saved to disk. To preserve the list, 
call the IVCmdMenu::ListGet member function and take steps to 
store the result. 

ListSet is much faster than the IVCmdMenu interface's Add, 
Remove, or Set member functions because list entries are 
substituted when a command is recognized and the menu is not 
recompiled. This means that ListSet can be called on an active 
menu without affecting performance. 



45 IVCmdMenu ::Num 



IVCmdMenu: :Num retrieves the total number of commands on a 
voice menu. 
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Syntax HRESULT Num( 

DWORD *pdwNumCmd 

); 

5 

Parameters pdwNumCmd 

[out] Address of a variable that receives the number of 
commands. 

1 0 Return Values This method returns NOERROR if successful, or one of these 
error values: 

• EJNVALIDARG 
VCMDERR_INVALIDCHAR 

• VCMDERR_MENUTOOCOMPLEX 
] 5 • VCMDERR_OUTOFMEM 

VCMDERR_VALUEOUTOFRANGE 



IVCmdMenu::Remove 

20 

IVCmdMenu::Remove removes the specified commands from the 
voice menu. " 

Syntax HRESULT Remove*' 

25 - DWORD dwCmdStart, 

DWORD dwCmdNum, 
DWORD dwFlag 

); 

30 P aram et ers dwCmd Start 

[in] Number of the first command in the menu to remove. 
Command positions are sequential, starting with 1 for the 
first command on the menu. \f dwFlag is the 
VCMD_BYJDENT1F1ER value, this parameter is 
35 ignored. 

dwCmdNum 

[in] Number of commands to remove or the identifier of 
the commands, depending on the value of dwFlag. If the 
sum ofdwCmdStart and dwCmdNum exceeds the total 
40 number of commands in the menu, the function removes 

as many commands as possible. 

dwFlag 

[in] Flag that identifies the nature of 'dwCmdNum. This 
parameter can be one of these values: 
45 • VCMD_BYJDENTIFIER 

VCMD_BY POSITION 
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Return Values This method returns NOERROR if successful, or one of these 
error values: . 

• EJNVA1IDARG 

• VCMDERRJNVALIDCHAR 

5 • VCMDERRJV4ENUTOOCOMPLEX 

• VCMDERR_OUTOFDISK 
VCMDERR_0UT0FMEM 

• VCMDERR_VALUEOUTOFRANGE 

1 0 Remarks For best results, you should deactivate the voice menu before 
calling Remove. Otherwise, the menu must be deactivated, 
recompiled, and reactivated before Remove rerurns. If the menu 
is already deactivated when Remove is called, the menu is not 
recompiled until the application activates it again. 

]VCmdMenu::Set 

IVCmdMenu::Set sets information for one or more commands in 
20 a voice menu. 

Syntax HRESULT Set( . 

DWORD dwCmdSiart, 
DWORD dwCmdNum, 
25 DWORD dwFlcg, 

SDATA dData 

); 

Parameters dwCmdStart 
30 [in] Number of the first command to set in the voice 

menu. Command positions are sequential, starting with 1 
for the first command on the menu. UdwFIag is the 
VCMD_BY ^IDENTIFIER value, this parameter is 
ignored. 

35 dwCmdNum 

[in] Either the number of commands to set or the identifier 
of the commands, depending on the value ofdwFlag. If 
the sum of dwCmdSiart and dwCmdNum exceeds the 
number of commands in the menu, the function sets as 

40 many commands as possible. 

dwFlag 

[in] Flag that identifies the nature of dwCmdNum. This 
parameter can be one of these values: 
VCMD_BYJDENTIF1ER 
45 . VCMDJBY_POSIT10N 

dData 

[in] SDATA structure that contains a pointer to a data 
buffer and the size of the buffer. The data buffer contains 
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a list of VCMDCOMM AND structures that describe the 
voice commands to set. Although they vary in size 
depending on the command data, the structures are 
contiguous within the list. 
5 ' 

Return Values This method returns NOERROR if successful, or one of these 
error values: 

• EJNVALIDARG 
VCMDERR_INVALIDCHAR 

1 0 • VCMDERRJV1ENUTOOCOMPLEX 

• VCMDERR_OUTOFD]SK 
VCMDERR_OUTOFMEM 
VCMDERR_VALUEOUTOFRANGE 

1 5 Remarks For best results, you should deactivate the voice menu before 
calling Set. Calling Set on an active menu can be fairly slow 
because the menu must be deactivated, recompiled, and 
reactivated before Set returns. If the menu is already deactivated 
when Set is called, the menu is not recompiled until the 

20 application activates it again. 



lVCnidMenu::Sethem 

25 IVCrncLMenu.iSetlteni tempoiaiily enables or disables a 

command on a voice menu. 

Syntax H RESULT Setltem( 

DWORD dwEnable, 
30 DWORD dwCmdNum, 

DWORD dwFlag 

); 

Parameters dwEnable 

35 M TRUE to enable the command or FALSE to disable it. 

dwCmdNum 

[in] Position or identifier of the command on the menu, 
depending on the value of dwFlag. Command positions 
are sequential, starting with 1 for the first command on the 
40 menu. 

dwFlag 

[in] Flag that identifies the nature of dwCmdNum. This 
parameter can be one of these values: 
VCMDJBYJDENTIFIER 
4 5 • VCMDJ3Y_POSITION 

Return Values This method returns NOERROR, if successful, or one of these 
error values: 
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Remarks 



10 



• E_INVALIDARG 

VCMDERR_OUTOFMEM 

If a command is disabled by using Setltem, the voice-command 
object sends a CommandOther notification rather than a 
CommandRecognize notification when it "recognizes" the 
disabled command. 

Setltem is much faster than the IVCmdMenu::EnableItem 
member function because the menu is not recompiled. This 
means that Setltem can be called on an active menu without 
affecting performance. 



15 IVCmdNotifvSink 



20 



The IVCmdNotifySink must be implemented by an application in 
order to receive notifications from the Voice Command object. In 
addition to the recognized command, an application can also be 
notified of events such as: beginning and ending of an utterance, 
menu activation, and the presence of interference. 



Method 

1 VCmdNot i fyS ink : : A tlribChanged 
IVCmdNotifySink::CommandOther 



IVCmdNotify'Sink::CommandRecognize 



lVCmdNotifySink::CommandStart 



IVCmdNotifySink: 
IVCmdNotifySink 
IVCmdNotifySink 
IVCmdNotifySink 
IVCmdNotifySink. 



rlnterference 
:MenuActivate 
:UtteranceBegin 
:UtteranceEnd 
:VUMeter 



Description 



A site attribute S;as 
cnanged. 

A spoken phrase was 
either recognized as 
being from another 
application's 
command set or was 
not recognized. 
Recognized as being 
from the application's 
command set. 
A spoken phrase was 
detected. 
Not Implemented 
Not Implemented 
Not Implemented 
Not Implemented 
Not Implemented 



25 



Remarks Not all IVCmdNotifySink methods are used by Auto PC S API. 
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JVCmdNotifySink::AttribChanged 

IVCmdNotifySink::AttribChanged notifies applications on a 
5 voice-command site that a site attribute has changed. 

Syntax HRESULT AttribChanged( 

DWORD dwAttribute 

); 

10 

Parameters dwAttribute 

[in] Site attribute that was changed. This parameter can 
be one of these values: 

IVCNSAC_AWAKE 
1 5 Awake state. 

IVCNSAC_AUTOGAINENABLE 

Automatic gain. 
IVCNSACDEV1CE 

Wave-in audio device. 
20 IVCNSACJENABLED 

Enabled state. 
IVCNSAC^MJCROFHON^ •- 

Current microphone . 
IVCNSACJDRIGiNATP 
25 The apphcation receiving ihiii notification 

originated the attribute change. 
IVCNSAC_SPEAKER 

Name of the current speaker. 
IVCNSAC_SR]V10DE 
30 Speech-recognition mode. 

IVCNSACJTHRESHOLD 

Confidence threshold. 

Return Values The return value is ienored. 

35 

Remarks The notification is sent only to applications that, when registered 
to use voice commands on the site, did one of the following: 

• Set the dwFIags parameter of the IVoiceCmd::Register 
member function to the VCMDRF_ALLBUTVUMETER 

40 value. 

• Set the VCMDRF_ATTR1BCHANGE bit. 
dwAttribute includes the IVCNSACJDRJGINAPP value only if 
the application sets an attribute by calling the IVCmdAttributes 
interface's EnabledSet, AwakeStateSet, DeviceSet, or 

45 SRModeSet member function. 
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]VCmdNotifySink::CommaDdOther 

IVCmdNotifySink::CommandOther is sent when a spoken phrase 
was e ^her recognized as being from another application's 
5 command set or was not recognized. 

Syntax HRESULT CommandOther( 

PVCMDNAME pName, 
PTSTR pszCommand 

10 ); 

pName 

[in] Address of a VCMDNAME structure that contains the 
• name of the voice menu that has the recognized command. 
If this parameter contains NULL, the command was not 
recognized. 
pszCommand 

[in] Address of the command string. If this parameter 
contains NULL, the command was not recognized. 

Return Values The return value is ignored. 

Along with the noti;ica:icij | -;1is application receives the address 
of the phrase. 

An application can use the CommandOther notification to 
monitor utterances and inform the user what was heard. An 
application should not rely on this notification for information 
about the recognition of its own commands. Most applications 
ignore this notification. 

The command string contains the words actually spoken by the 
user. If the command contains a list name, the command string 
may not match the words of the command. For example, the 
string pointed to by pszCommand might be "Send mail to Fred" 
whereas the command string is "Send mail to name." 

The notification is sent only to applications that, when registered 
to use voice commands on the site did one of the following: 

• Set the dwFIags parameter of the 
IVoiceCmd::Register member function to the 
VCMDRF_ ALLB UT VUM ETER value. 

• Set the VCMDRFJTMDOTHER bit. 
If two or more voice menus contain the same phrase and this 
phrase is recognized, it is indeterminate which of the menus will 
cause the engine to call the 

IVCmdNotifySink::CommandRecognize notification and which 
will cause it to call CommandOther. This happens only if the 
menus are all global or all window specific. 



Parameters 

15 



Remarks 

25 
30 
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IVCmdNotifySink::CommandReeognize 

JVCmdNoiirySink::CommandRecognize is sent when a spoken 
phrase is recognized as being from the application's command 
set. 

Syntax HRESULT CommandRecognize( 

DWORD dwJD, 
PVCMDNAME pvCmdName, 
DWORD dwFlags, 
DWORD dwActionSize, 
PVOID pAction, 
DWORD dwNumLists, 
PTSTR pszListValues, 
PTSTR pszCommand 

y> ■ 

Parameters dwJD 

[in] Identifier of the command that was recognized. The 

command identifier is stored in ih-e chvID member of the 

" ■ " • - " VCMpCQMMA>:B nracturclh&'dcfmes the command. 
pvCmdName 

[in] Address of s YCMDNAMF. structure containing the 

voice menu that has the recognized command. 
dwFlags 

[in] VCMDCMDJVERIFY if the application should 
request verification from the user or NULL if verification 
is not required. To request verification, the application 
should display a dialog box. An application would 
typically require verification for a destructive or 
irreversible command such as "Format disk." 
dwActionSize 

[in] Size of the data in pAction. 

p Action 

[in] Address of a string that contains action data to 
accompany the recognized command. The action data is 
obtained from the VCMDCOMMAND structure for the 
command. 
dwNumLists 

[in] Size, in bytes, of the list data for the command. If a 
command does not contain any list fields, this parameter is 
zero. 
pszListValues 

[in] Address of a list of one or more null-terminated 
strings that correspond to the phrase from each list in the 
order that they occur in the command. For example, if the 
command is "Set the time to number AM or PM " this 
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parameter points to "Ten\0PM" (the last 4 \0 $ is implicit in 
C notation). 
pszCommand 

[in] Address of the command string for the command that 
was recognized. 

Return Values The return value is ignored. 

Remarks Along with the notification, the application receives the text of 

the phrase and the action data that was supplied by the application 
when it originally defined the command. 

You should not use the contents of pszCommand to identify the 
recognized command. Instead, use the data in pAction or the 

1 5 identifier in dwJD to determine which command was recognized. 

The pszCommand string may not contain the same string that you 
specified in the VCMDCOMMAND structure because it is 
possible for the user to edit the text for commands for your 
application using Microsoft Voice or another voice-aware 

20 application. 

* - The notification is sent to all applications 'Shai pre se-gisMrsd vsS;' 

-'he- voice-command site, regardless of the tzninkofihtduFiags 
parameter of the IVoiceCmd::Register member function when the 
application registered to use voiCe commands. 

If two or more global voice menus (or two or more window- 
specific voice menus) contain the same phrase and the engine 
recognizes that phrase, the engine calls CommandRecognize for 
30 one menu and IVCmdNotifySink::CommandOther for the other. 

The engine determines which notification to call for each menu; 
an application cannot determine which notification will be called. 



35 



IVCmdNotifySink::CommandStart 



40 



JVCmdNotifySinkrrCommandStart is sent when a spoken phrase 
is detected. 

Syntax HRESULT CommandStart(); 

Return Values The return value is ignored. 

45 Remarks The notification is sent only to applications that, when registered 
to use voice commands on the site, did one of the following: 
• Set the dwFlags parameter of the lVoiceCmd::Register 

member function to the VCMDRF_ALLBUTVUMETER 

value. 
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Set the VCMDRF_CMDSTART bit. dwAttribute 
includes the IVCNSAC_OR]GINAPP value only if the 
application sets an attribute by calling the 
IVCmdAttributes interface's EnabledSet, AwakeStateSet, 
DeviceSet, or SRModeSet member function. 

IVCmdNotifySink::lnterference 

1 0 IVCmdNotifySink::Interference notifies the application that the 

engine cannot recognize speech properly for a known reason. 

Syntax HRESULT Interference( 

DWORD dwType 

15 ); 

dwType 

[in] Type of interference. This parameter can be one of 
these values: 

SRMSGINT_AUD10DATA_STARTED 

The engine has resumed receiving audio data from 
; the ftudip.isoiirce/ . v-*-y:V^ v ; v . s - 
. S"RjMSGriv7_Al;D]OlvA ; iA^STQPPED .'- ~ ;: * 

The engine has stopped receiving audio data from 
the audio source.. - : 

SRMSGINT_NOISE 

The background noise is too high. 
SRMSGINT_N0S1GNAL 

The engine cannot detect a signal, possibly 
because the microphone is off or unplueged. 
SRMSGINTJTOOLOUD 

The speaker is too loud; recognition results may be 
degraded. 
SRMSGINTJTOOQU1ET 

The speaker is too quiet; recognition results may 
be degraded. 

Return Values The return value is ignored. 

40 Remarks The notification is sent only to applications that set the 

dwFlags parameter of the IVoiceCmd::Register member function 
to the VCMDRP_ALLBUTVUMETER value when the 
application registered to use voice commands on the site. 

45 



5 



Parameters 

20 
25 
30 
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IVCmdUserWord 

The IVCmdUserWord interface allows an application to enable 
the speaker-dependent and speaker-independent templates, and to 
5 add new words to the speaker-dependent template. 



20 



25 



Method : Description 

IVCmdUserWord::AddRemoveSIFile Installs or uninstalls 

speaker-independent 
template extension 
files. 

IVCmdUserWord: :ModifyTraining Specify which 

templates are 
enabled for a 
particular phrase. 

IVCmdUserWord::GetPhraseList Gets the current . 

phrase list. 

IVCmdUserWord::QueryPhrase Determines what kind 

of templates a phrase 
has and whether or 
not they are enabled. 

^- ~ Ti3iii a list ci er- 

. "•''* defined ohrases; 



I VCmdl Jbcv Wordr-Train . 



Remarks This interface is ar: extension oi :hb Microsoft Speech API, added 
to meet the needs of the Auto PC. It is designed specifically for 
10 a " isolated-word recognizer. Continuous speech recognizers 

should have training templates for all phrases, and should not 
need to train user-defined words. Any function call on this 
interface will affect the current speaker only. 

1 5 Templates hold information that the engine uses to recognize a 

phrase. There are two types of templates for the Auto PC: 
speaker-independent and speaker-dependent. There is one 
speaker-independent template for each phrase. Each speaker can 
have one speaker-dependent template for each phrase. 

To create a speaker-dependent template, a user must "train" the 
object to recognize their particular speech pattern. Speaker- 
independent recognition can only be enabled or disabled. It 
cannot be modified by the user. 

The two templates operate independently of each other. An 
application can enable a speaker-dependent template whether or 
not the speaker-independent template is available. Enabling both 
templates may achieve better recognition accuracy. 



30 
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]VCmdUserWord::AddRemoveSlFile 

The IVCmdUserWord::AddRemoveSIFiIe method installs or 
uninstalls speaker-independent template extension files. 

Syntax HRESULT AddRemoveSIFILE( 

LPCTSTR IpszFile, 
BOOL blnstalty 

1 0 Parameters IpszFile 

Pointer to the path of the file to install or uninstall. 
blnsiall 

Indicates whether to install or uninstall a file, TRUE .to 
install, FALSE to uninstall 



15 



30 



IVCmdUserWord::GetPhraseList 



The !VCmdUserWord::GetPhraseList method gets the words in 
20 the installed vocabulary. 

- Syntax V HRESlJLTGetPhraseLisj.f : ' :■ 
' "' """ DWORD dwFlags' 

PWSTR IpBuf 

25 ... . PD.WORD,- *pdwByU:Cnt- - 

); 



Parameters dwFlags 

There are two flags that can be set, one for each word list. 



--. - - -> til fcV 

Flag 


Description 


SRPHRASE_SI 


Returns the speaker- 




independent list. 


SRPHRASE_SD 


Returns the speaker- 




dependent list. 



IpBuf 

Pointer to the buffer where the phrase list will be stored. 
PdwByieCnt 

The size of the buffer allocated to hold the list, in bytes. If 
35 the method returns successfully, it holds the actual number 

of bytes in the buffer. 

Return Values This method returns NOERROR if successful, or one of these 
error values: 

40 VCMDERR_VALUEOUTOFRANGE 

The allocated buffer is too small. When this occurs, 
GetPhraseList will set pdwByteCm to the buffer size 
needed. 
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Errors 



5 Remarks 



If there is an error, the appropriate HRESULT should be 
returned. 

If both of these flags, SRPHRASE SI and SRPHRASE SD are 
set, and if a word has both speaker-independent and speaker- 
dependent templates, the same word shows up in the buffer twice 



1 0 JVCmdUserWord::ModifyTraiDing 



15 



Svmax 



20 



Parameters 



25 



30 



35 



40 



45 



The IVCmdUserWordrrModifyTraining method allows an 
phm" 110 " 10 SPeC, ' fy WWCh ,emp,a,es m enabled for a Particular 

HRESULT Modify Training( 
LPTSTR IpszPhrase 
^ DWORD dwFIags 

IpszPhrase 

The phrase of interest. 

' dwFjags ' . ■■■■■■■ ■ .... • • • ' 

. SRPHRASE_SI 

Specifies the speaker-independent template 
" - SRPHRASE_SD ■ 

Specifies the speaker-dependent template 
SRPHRASE_SI_ENABLE ' 
Enables or disables a phrase on the speaker- 
independent template. 
SRPHRASE_SD_ENABLE 

Enables or disables a phrase on the speaker- 
dependent template. 
SRPHRASE_SD_ERASE 

Erases the speaker-dependent template for a 
phrase. 

SRPHRA SE_PERMANENT 

When set, makes any changes permanent. 

Return Values This method returns NOERROR if successful, or one of these 
error values: 

SRERR_PHRASENOTFOUND 

The P^ 3 ^ was not found in either template. 
SRERR_TEMPLATENOTFOUND 

The template is not available. 
Other Errors 

If there is another error, the appropriate HRESULT should 
be returned. 
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Remarks Templates are enabled independently of each other. Either or 
both may be enabled at any given time. When setting a flag to 
enable or disable a template, the corresponding flag to select the 
template must also be set. For example, to enable the speaker- 
5 dependent template, user SRPHRASE_SD | 

SRPHRASE_SD_ENABLE. 

The phrase string can contain alphabetic characters and intraword 
punctuation. It may not contain pronounced symbols such as 
1 0 numbers ("345" is not a valid string). Avoid ambiguous 

pronunciation. Instead of IEEE, use "I triple E," for instance. 

IVCmdUserWord::QuervPbrase 

15 

The IVCmdUserWord::QueryPhrase method is used to determine 
what kind of templates a phrase has and whether or not they are 
enabled. 

20 Syntax HRESULT QueryPhrase( 

LPTSTR IpszPhrase 
DWORD *pdw Value 

• - - ); 

25 Parameters IpszPhrase 

The phrase of interest. 
pdw Value 

Returns flags indicating the training templates associated 
with the phrase. 
30 SRPHRASE_SI 

The phrase has a speaker-independent template. 
SRPHRASE_SI_ENABLE 

The speaker-independent template is 

enabled/disabled. 
35 SRPHRASE_SD 

The phrase has a speaker-dependent template. 
SRPHRASE_SDJENABLE 

The speaker-dependent template is 

enabled/disabled. 

40 

Return Values This method returns NOERROR if successful, or one of these 
error values: 
Errors 

If there is an error, the appropriate HRESULT should be 
45 returned. 

Remarks The phrase string can contain alphabetic characters and intraword 
punctuation. It may not contain pronounced symbols such as 
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numbers ("345" is not a valid siring). Avoid ambiguous 
pronunciation.. Instead of IEEE, use "I triple E " for instance. 



5 JVCmdUser\Vord::Train 

The IVCmdUserWord::Train method is called by the application 
to train a list of user-defined phrases. ! 

10 Syntax HRESULT Train( 

LPTSTR IpPhrases 
DWORD dwSize 
DWORD hHandle 
DWORD dwFlags 

15 ); 

Parameters IpPhrases 

A pointer to a sequential list of Unicode text strings. Each 
string is terminated by a Unicode NULL character. The 
20 end of the list is also indicated by a NULL. 

dwSize 

. .... The .number 7 o£ Unicode characters in the list, including 
NULL ctiarac-tere (not xhe number of bytes!). 
hHandle 

25 No? implcmer**td in AutoPC version 1 . This parameter 

should be set to zero. 
dwFlags 

Not implemented in AutoPC version L This parameter 
should be set to zero. 

30 

Return Values This method returns NOERROR if successful, or one of these 
error values: 
Errors 

If there is an error, the appropriate HRESULT should be 
returned. 

The phrase string can contain alphabetic characters and intraword 
punctuation. It may not contain pronounced symbols such as 
numbers ("345" is not a valid string). Avoid ambiguous 
pronunciation. Instead of IEEE, use "I triple E," for instance. 



35 

Remarks 

40 



IVoiceCmd 

45 

The IVoiceCmd interface registers an application with a voice- 
command object. It is also used for tasks such as creating menus 
and menu enumerators. 
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Method 



Description 



]VoiceCmd::CmdMimic 



I Vo iceCmd : :M enuCreate 
IVoiceCmd::MenuDe]ete 

IVoiceCmd::MenuEnum 
TVoiceCmd: .Register 



Supplies a voice-aware 
application with the equivalent of 
a spoken voice command. 
Creates a voice-menu object. 
Deletes a menu from the voice- 
menu database. 

Creates a voice-menu enumerator. 
Registers an application to use 
voice commands. 



Remarks This interface is supported by all voice-command objects. 



5 ]VoiceCmd::CmdMimic 

The IVoiceCmd::CmdMimic method supplies a voice-aware 
application with the equivalent of a spoken voice command. 

10 Syntax HRESULT CmdMimic( 

PVCMDNAME pMenu, 

-~ " ~ "•' PTSTR f&zCcinmarid 

- .,,_ ); . -,, --.-v. , - • 

15 Parameters pMenu 

[in] Address of a VCMDNAME structure identifying the 
menu that contains the command to mimic. 
pszCommand 

[in] Address of a string that contains the command to 
20 mimic. 



Return Values This method returns NOERROR if successful, or one of these 
error values: 

E_INVALIDARG 
25 • VCMDERR_CANN0TM1M1C 

VCMDERRJNVAL1DCHAR 
VCMDERRJYIENUDOESNOTEX1ST 
VCMDERR_OUTOFMEM 
VCMDERR_VALUEOUTOFRANGE 
30 • VCMDERR INVALIDCHAR 



Remarks CmdMimic parses the command string and eliminates white 

space and punctuation, and then the member function compares 
the result with each command on the voice menu until it finds a 
35 match. The comparison is case-insensitive, and the command 

string can include phrases from lists. If the string matches a 
command in the voice menu, it is recognized. Otherwise, the 
function returns an error. 
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An application can. call CmdMimic to play back voice macros to 
another application, somewhat like playing back keystrokes and 
mouse messages in Windows. 

The voice menu must be active before an application can mimic 
its commands. j 



10 IVoiceCmd::MeDuCreate 



15 



20 



25 



30 



35 



40 



45 



The IVoiceCmd::MenuCreate method creates a voice-menu 
object to represent a new or existing voice menu for an 
application. 

Syntax HRESULT MenuCreate( 

PVCMDNAME pName, 
PLANGUAGE pLanguage, 
DWORD dxvFlags, 
PIVCMDMENU *pplVCmdMenu 

); 

Parameters pName , 

[in] Address of a VCMDNAME structure thzt Identi fies 
the menu to create Th<j VCMDNAME structure contains 
an application name, such as "Excel," and a state name, 
such as "Main menu" or "File Open dialog box." 
pLanguage 

[in] Address of a LANGUAGE structure that indicates the 
language to use for the menu. If this parameter is NULL, 
the default language for the site's speech-recognition 
mode is used. 
dxvFlags 

[in] Flag that indicates how to create the menu. This 

parameter can be one of these values: 

VCMDM C_CRE ATE_AL WA YS 

Creates an empty menu with the given name. If a 
menu by that name already exists in the voice- 
menu database, it is erased. The new menu is 
stored in the database when the menu object is 
released. 

VCMDMC_CREATE_NEW 

Creates an empty menu with the given name. If a 
menu by that name already exists in the voice- 
menu database, the function returns an error. The 
new menu is stored in the database when the menu 
object is released. 
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10 



15 



20 



VCMDMC_CREATE_TEMP 

Creates an empty menu with the given name. If a 
menu by that name already exists in the voice- 
menu database, the function returns an error. The 
new menu is temporary and is discarded when the 
menu object is released. 

VCMDMCJDPEN_ALWAYS 

Opens an existing menu with the given name. If 
the menu does not exist, the function creates a 
new, empty menu. The new menu is stored in the 
database when the menu object is released. 

VCMDMC_0PEN_EX1STING 

Opens an existing menu. If the menu does not 
exist, the function returns an error. 

ppIVCmdMenu 

[out] Address of an IVCmdMenu interface for the newly 
created voice-menu object. The application uses the 
pointer to this interface to call IVCmdMenu functions on 
the voice-menu object. If an error occurs, this parameter 
receives NULL. 



25 



30 



Return Values This method returns NOERROS if •: oji/cf.ssful or ov 
error values: 

E_INV Al ID ARG 
- VCMDERR_CANTCREATESTORAGE " 
VCMDERR_MENUDOESNOTEXIST 
VCMDERRJV1ENUEXIST 
VCMDERRJ3UTOFDISK 
VCMDERR_OUTOFMEM 
VCMDERR_VALUEOUTOFRANGE 



o;f !her ; e 



Remarks 



35 



40 



45 



An application can create a voice-menu object by loading an 
existing voice menu from the voice-menu database or creating a 
new voice menu. A voice menu need not be stored in the 
database; an application can create a temporary voice menu by 
setting dwFlags to the VCMDM C_CRE ATEJTEMP value. A 
temporary voice menu persists until the menu object is released. 

An application can create more than one voice-menu object to 
represent the same menu — either one of its own menus or a 
menu for another application. For example, one application 
might do this to enumerate another application's menus. 

More than one application can use the same voice-menu object. 
For example, Application A might call the 
IVoiceCmd::CmdMimic member function on a voice-menu 
object that represents a menu for Application B, while 
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Application B uses the same menu object to recognize commands 
spoken by the user. 



5 IVoiceCmd::MenuDelete 

The ]VoiceCmd::MenuDelete method deletes a menu from th^ 
voice-menu database. 

10 Syntax HRESULT MenuDelete( 

PVCMDNAME pName 

); 

Parameters pName 

1 5 fin] Address of a VCMDNAME structure that identifies 

the menu to delete. 

Return Values This method returns NOERROR if successful, or one of these 
error values: 
20 • EJNVALIDARG 

• VCMDERR_MENUACTIVATE 

■ • ■■->■ . YOM^RR^MENt^ v '' : : " 

• * VCMDERR_MENuOFEN 
VCMDERRJ3UTOFMEM 



Remarks A menu cannot be deleted if it is currently open and the 
application is actively listening for its commands. 



This function deletes the storage in the database for the menu (if it 
30 exists) and releases the voice-menu object that was created by the 

IVoiceCmd::MenuCreate member function. After a menu is 
deleted, the pointer to its IVCmdMenu interface is invalid, so it 
should be set to NULL. 



IVoiceCmd::MenuEnum 



The IVoiceCmd::MenuEnum method creates a voice-menu 
enumerator that allows an application to enumerate menus in the 
40 voice-menu database. 

Syntax HRESULT MenuEnum( 

DWORD dwFlags, 
PTSTR pszAppIicationFiher, 
45 PTSTR pszSiateFilter, 

PJVCMDENUM *ppiVCmdEnum 

); 
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Parameters dwFlags 

[in] Indicates whether to enumerate active menus or open 
menus (those that have voice-menu objects, whether or 
not they are also active). This parameter can be certain 
combinations of these values: 
VCMDEF_ACTTVE 

Enumerates only active menus. 
VCMDEFDATABASE 

Enumerates all menus in the voice commands 
database. 
VCMDEF_PERMANENT 

Enumerates only permanent menus. 
VCMDEF_SELECTED 

Enumerates open menus, whether or not they are 
also active. 
VCMDEFJTEMPORARY 

Enumerates only temporary menus. 
VCMDEF_ACTIVE and VCMDEF_SELECTED 
are mutually exclusive, as are 
VCMDEFJTEMPORARY and 
VCMDEF_PERMANENT. If both values are 
. > .^ : . specified,, the function returns as error. 
v ' '* r VJ> ; VCMDEF_Ti:MPORARY and 

VCMDEF_PFRfvlANENT are ignored if neither 
V*CMDEF_ ACTIVE and VCMDEF_SELECTED 
are specified. In other words, they do not apply if 
you want to enumerate the menus in the database. 
By definition, if a menu is active, it is selected. 
pszApplicationFilter 

[in] Address of the name of the application for which to 
enumerate menus. This name is the same as that in the 
szApplication member of the VCMDNAME structure 
passed to the IVoiceCmdnMenuCreate member function. 
If this parameter is NULL, menus for all applications, ■ 
except those eliminated by dwFlags and pszStateFilter, 
are enumerated. 
pszStateFilter 

[in] Address of a string that contains the name of the state 
for which to enumerate menus. This is the same as in the 
szState member of the VCMDNAME structure passed to 
MenuCreate. If pszApplicationFilter is NULL, all menus 
except those eliminated by dwFlogs and this parameter are 
enumerated. 
ppiVCmdEnwn 

[out] Address of a variable that receives a pointer to an 
IVCmdEnum interface for the newly created voice-menu 
enumerator. If an error occurs, this parameter receives 
NULL. 
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Return Values This method returns NOERROR if successful, or one of these 
error values: 

EJNVALIDARG 

• VCMDERR^INV ALIDM ODE 
5 • VCMDERR_OUTOFMEM 

• VCMDERR_VALUEOUTOFRANGE 
VCMDERRJV1ENUDOESNOTEX1ST 

Remarks A menu can use a voice-menu enumerator to find and modify 
1 0 unknown menus or to show menu status to the user. 



The voice-menu enumerator persists until all references to it are 
released, even if the voice-command object is released. 

15 

IVoiceCmd::Register 

The !VoiceCmd::Register method registers an application to use 
voice commands on a site. An application must call this function 
20 before it can use voice commands. 

% - Syntax HRESULT Register( \ '."v 

" - P7 STR pszSite, 

PIVCMDNOTIFYSINK pNbtifyhnerface, - 
25 UD UDNotifylnierface, 

DWORD dwFlags, 
PVCSITEINFO pSitelnfo 

); 

30 Parameters pszSite 

In Auto PC, must be null or empty. 
pNoiifyJnterface 

[in] Address of the notification interface that receives 
notifications from the voice-command object. The 
35 interface identifier is specified by IIDNotifylnterface. If 

this parameter is NULL, no notifications will be sent. 

Because passing the pointer to the voice-command object 
does not transfer ownership of the notification interface, ' 

40 the voice-command object must call the AddRef member 

function of the notification interface before returning from 
the call to Register. The voice-command object must also 
call the Release member function of the notification 
interface when it closes. The calling application must 

45 release any reference counts it holds on the notification 

interface after calling Register, unless it needs the 
notification object to be valid when the voice-command 
object releases it. 
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UDNoiifylnierface 

[in] GUID that uniquely identifies the type of notification 
sink being passed to the voice-command object. It must 
be irojVCmdNotifySinkW. 
5 dwFlags 

[in] Flag that indicates whether the application is to i 
receive all notifications. This parameter can be one of] 
these values: 

VCMDRF_ALLMESSAGES 
1 0 Sends all notifications to pNotifylnterface. 

VCMDRF_ALLBUTVUMETER 

Sends all but VUMeter notifications to 
pNotifylnterface. 
VCMDRF_VUMETER 
1 5 Sends VUMeter notifications to 

pNotilylnterface. 
VCMDRf_NOMESSAGES 

Does not send notifications. 
IfdwFIags is 0 (zero) or NULL, only the 
20 IVCmdNotifySink::CommandRecogni2e notification is 

sent. 
pSiielnfo - 

[in] Ag Jj : : ;o oi';: YCSlTIiiKFO structure that contains 
setting* to *pply to the site, such as the speaker, 
25 confidence threshold, ^nd speech-nxognition node. The 

settings are applied even if the site is already open. If this 
parameter is NULL, the voice-command object uses the 
settings from the registry. If there are no registry settings, 
it uses the default settings, typically those for the 
30 computer. 

Telephony applications will pass this information to 
ensure that the proper settings are selected. Other 
applications will set this parameter to NULL to leave the 
site settings unchanged from previous values. 



35 



40 



45 



Return Values This method returns NOERROR, if successful, or one of these 
error values: 

EJNVALIDARG 

VCMDERR^CANTCREATEAUDIODEVICE 
V CMDERR_C ANTCRE A TE S RENUM 
VCMDERR_CANTSELECTENGINE 
VCMDERR_CANTSETDEV1CE 
VCMDERRJNVALJDMODE 
VCMDERR_NOFIND INTERFACE 
VCMDERR_NOSITEINFO 
VCMDERR_OUTOFMEM 
VCMDERR^SRFINDFAJLED 
VCMDERR_VALUEOUTOFRANGE 
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An application cannot call Register a second time for the same 
voice-command object. If a voice-command object is already 
registered, calling Register returns an error. To change sites, the 
application must call CoCreatelnstance to create a new voice- 
command object for the desired site. 

An application must call Register before it can call any of the 
following member functions: 

IVCmdMenu::Deactivate, IVCmdMenu::ListGet, 
IVCmdMenu::ListSet 



SUBSTITUTE SHEET (RULE 26) 



WO 99/49394 PCTAJS99/06223 

207 



Detailed Description of Data Structures for a Voice Command API 
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Chapter 24 

V CM D CO M M AND 

5 Provides information about a command in a voice menu, 

typedef struct { // vccmd 



DWORD 


dwSize; 


DWORD 


dwFlags; 


DWORD 


dwID; 


DWORD 


dwCommand; 


DWORD 


dwDescription; 


DWORD 


dwCategory; 


DWORD 


dwCommandText; 


DWORD 


dwAction; 


DWORD 


dwActionSize; 


BYTE 


abData[]; 



} VCMDCOMMAND, *PVCMDCOMMAND; 
dwSize 

Size, in bytes, of the VCMDCOMMAND structure, 
including the amount .-Uocatec fcr iiliDal;.., "CYr. extents 
of abD?ta must be doubleword- siig^CG, so round dwSize 
up to the nearest whole doubleword. 
dwFlags . 

Flags that indicate information about the command. This 

member can be a combination of these values: 

Value Description 

VCMDCMD_D1SABLED_PERM The command was disabled 

by using the IVCmdMenu:: 
Enableltem member 
function so that voice 
commands will not 
recognize it. The command 
is not compiled into the 
voice menu. 

VCMDCMD_DISABLED_TEMP The command was disabled 

by using the 
IVCmdMenu ::SetItem 
member function. The 
command is still compiled 
into the voice menu, 
however, so it can be re- 
enabled without 

recompilation of the menu. 



20 Members 



25 
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Value 

VCMDCMD VERIFY 



VCMDCMD CANTRENAME 



Description ■ 

The application should 
prompt the user to 
verify the command 
before carrying it out. 
For example, this 
value should be set for 
a "Delete File" 
command. This value 
may be combined with 
either of the other 
values. 

(New for 3.0). This 
indicates that the 
command is 
automatically 
generated and that 
navigator applications 
(such as Microsoft 
Voice) shouldn't allow 
.u->c>v.*f? *?nsme the - ■■" 
torfrir.and. For 
example: A set of 
ccr/iji^jids thai aie 
generated by 
extracting all of the 
menu items in the 
currently running 
application would have 
this flag set since there 
would be little point in 
users renamine them. 



10 



15 



dwID 

Command identifier. This member can be used to identify 
a command to modify, or it can be used for notifications. 
dwCommand 

Offset from the beginning of this structure to first 
character of the voice command string (ANSI or Unicode, 
depending on which character set was used in the 
application). For example, the voice command string 
might be "Open the file" and the character at the offset 
specified by dwCommand would be '0\ In languages 
such as Japanese that have both a phonemic and symbolic 
character set, the dwCommand member is the offset to a 
phonemic string. 

Within the command string, the following characters have 
special meaning: 
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Character Meaning _^ 

Indicates the name of a list of words or phrases 
that can be spoken at this point in the command. 
For example, the command string "Send mail to 
name" contains a list called "name." To add 
phrases to the list, use the IVCmdMenu::ListSet ' 
member function. 

{ } Reserved for future use. 

£] Reserved for future use. 

dwDescription — — 

Offset from the beginning of the structure to first character 
of a string that describes the action performed by the 
command. 
dwCategory 

Offset from the beginning of the structure to the first 
character of a string that indicates the category to which 
the command belongs. 

Commands in a voice menu should be organized in 
different categories to help the user browse through lists 
of commands more easily. This is similar in concept to 
-Wincpws menus, ^rSfefr organize ^/^n^an^s lender menu 
-.. earner such as "File" "Edit/ 1 "View," and so on. For best 
results, you should use 20 or fewer categories. 
dwCommandText 

Offset from the beginning of the structure to the first 
character of the command text, which is the string that is 
displayed to the user when he or she requests a list of 
available voice commands. If this member is NULL, an 
application uses the text pointed to by dwCommand, 
which is the voice-command string used in the 
application's user interface. 

Most applications written for European languages will set 
this member to NULL because the language uses only one 
character set. Applications written for languages that have 
both a phonemic and symbolic character set, such as 
Japanese, will store the phonemic representation of the 
command in dwCommand and the symbolic 
representation (which is preferred by the user) in this 
member. 
dwAction 

Offset from the beginning of the structure to the first byte 
of a block of data that is sent to the application when the 
command is spoken. 

Data passed with a command is not interpreted by voice 
commands; it is up to the application to determine whether 
the data is valid and to act upon it. Always check the 
validity of the data, because it is susceptible to being 
changed — accidentally or intentionally — by other 
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applications, just as other applications can change an .INI 
file or registry file. 
dwActionSize 

Number of bytes required to store the block of data 
indicated by dwAction. 

abData 

Amy of type BYTE that contains the command string; its 
description, its category, and additional data (if any) to 
pass to the application along with the command. Because 
all of the items in abData are doubleword-aligned, the size 
of abData should be a multiple of 4. All strings should be 
null-terminated (\0). 

Because of the items indicated by offsets into abData are 
doubleword-aligned, the offsets specified by 
dwCommand, dwDescription, dwCategory, dwAction, 
and dwActionSize should be multiples of 4. 



VCMDNAME 

20 

Contains strings that uniquely identify the application and state to 

... ^ . , ,\v:hijL*h, a voice menu belongs. - ;,v; 

typedef struct { // vcn 
2 * ... TCHAR s2Applicat>ori[VCMD APPLEN]; 

TCHAR szState[VCMD STATELEN]; 
} VCMDNAME, *P VCMDNAME; 

szApplication 

30 Name of the application — for example, "Microsoft 

Word." The application name must be unique among all 
applications registered to use voice commands on the 
user's computer. 

szState 

35 Unique name of the application state in which the voice 

command set is valid. An application state usually 
corresponds to an active window or dialog box — for 
example, "Main Window" or "Set Font Dialog." 

40 

VCSITE1NFO 

Provides information about the audio device, speech-recognition 
mode, and other attributes of a voice-command site. 

45 

typedef struct { // vcsi 

DWORD dwAutoGainEnable; 
DWORD dwAwakeState; 
DWORD dwThreshold; 
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DWORD dwDevice; 

DWORD . dwEnable; 

TCHAR szMicrophone[VCMD MICLEN]; 

TCHAR szSpeaker[VCMD_SPEAKERLEN]; 

5 GUID gModelD; 

} VCSITEINFO, TVCSITEINFO 

dwAutoGainEnable 

Value from 0 to 100 that indicates the state of the 
1 0 automatic gain for the incoming audio stream to be used 

by the site. 
dwAwakeState 

TRUE if the site is awake for purposes of speech 
recognition or FALSE if the site is asleep. 
1 5 dwThreshold 

Value from 0 to 1 00 that indicates the recognition 
threshold for the speech-recognition engine to be used by 
the site. 
dwDevice 

20 Device identifier of the wave-in audio device to be used 

by the site. The device identifier can be obtained by 
- - calling ihe wavdnGe^NiimD^ 

multimedia fknccions. 
dwEnable 

25 . TRUE if speech-reLOgniuon is e-iabieti for the she 61"^ 

FALSE if speech-recognition is disabled. 
szMicrophone 

Name of the current microphone for the audio source to be 
used by the site. 
30 szSpeaker 

Name of the current speaker for the site. 
gModelD 

GUID that uniquely identifies the speech-recognition 
mode to be used by the site. The GUID for a speech- 
es recognition mode can be obtained by using a speech- 
recognition enumerator. For more information about 
speech-recognition enumerators, see section, "Low-Level 
Speech Recognition API." 

40 Remarks An application can pass a pointer to a VCSITEINFO structure 
with the IVoiceCmd::Register function to set the audio device, 
speech-recognition mode, and other attributes of a voice- 
command site, even if the site is already open. 
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Chapter 25 
VTSITEINFO 



Specifies an audio device, a text-to-speech mode, and the talking 
speed for a voice-text site and indicates whether voice text is 
enabled or disabled for the site. 



typedef struct { // vtsi 
10 DWORD dwDevice; 

DWORD dwEnable; 

DWORD dwSpeed; 

GUTDgModelD; 
} VTSITEINFO, *PVTS1TEINF0; 

15 

Members dwDevice 

Device identifier of the wave-out audio device to be used 
by the site. The device identifier can be obtained by 
calling the waveOutGetNumDevs and 
20 waveOutGetDevCaps multimedia functions. 

dwEnable 

if voice ie^i ii io.be dii abl-^. " 
dwSpeed 

25 • . . Baseiine average- tajjcir?g speed/^words per mihuie; for 

the text-to-speech mode to be used by the site. 
gModelD 

GUID that uniquely identifies the text-to-speech mode to 
be used by the site. The GUID for a text-to-speech mode 
30 is obtained from a text-to-speech enumerator object. For 

information about text-to-speech enumerators, see the 
section, "Low-Level Text-to-Speech API." 

An application can specify the address of a VTSITEINFO 
35 structure in a call to the IVoiceText::Register member 

function to set the voice, speaking speed, and other 
attributes of a voice-text site, even if the site is already 
open. Telephony applications typically do this to ensure 
that the proper information is selected for the site. 
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The IAPCSpeech interface is a high level Auto PC simple speech 
interface. 

The function CreateAPCSpeechObject should be called to get the 
IAPCSpeech interface because APCSpeechObj cannot be created 
using CoCreatelnstance. 



IAPCSpeech Methods 

Methods Description 

IAPCSpeech: :AddRef\vscesdk_I A Increments the reference 
PCSpeech_AddRef count for an interface on a 

speech object. 

IAPCSpeech:: Add VMenuComma Adds a command to the voice 
ndwcesdk_lAPCSpeech_AddVM menu pmenu. 
enuCommand 

■ . r . IAPCSpeech: :AttribGetwcesdk J Gets speech- related rrei^na.*. - 

APCSper;ch_AttribGet 

IAPCSpeech: :AttribSetwcesdk J Sets or changes speech- 
.._ APCSpeech_AttribSet related settings. 

IAPCSpeech: :CreateVMenuwcesd Creates a voice menu. 
k_lAPCSpeech_CreateVMenu 

!APCSpeech::Quen'Interfacewces Returns a pointer to an 
dkJAPCSpeech^Querylnterface IAPCSpeech interface. 
lAPCSpeech::Releasewcesdk JA Decrements the reference 
PCSpeech_Release count. 
!APCSpeech::SpealovcesdkJAP Says or speaks the string 
CSpeech_Speak stored in szTTS using TTS. 
I APCSpeech::TrainwcesdkJAPC Trains the application to 
SpeechJTrain recognize a user command. 
lAPCSpeech::VoiceHelpStartwce Is called by the shell to start 
sdk_lAPCSpeech_VoiceHelpStart voice help. 
IAPCSpeech::VoiceHelpStopwces Is called by the shell to stop 
dk IAPCSpeech VoiceHelpStop voice help. 



IAPCSpeech::AddRef 

The IAPCSpeech::AddRef method increments the reference count 
20 for an interface on a speech object. 

Syntax STDMETHODJULONG) IAPCSpeech::AddRef(THlS) PURE; 
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IAPCSpeech::AddVMenuCommand 



LAPCSpeech::AddVMenuCommand adds a command to the 
voice menu pMenu. 

5 

Syntax STDMETHOD IAPCSpeech::AddVMenuCommand(THIS_ 

PIVCMDMENUW pMenu, 
LPTSTR szCmdString, 
UINT dwCmdlD, 
10 DWORD dwFlags, 

PVOID p) PURE; 

Parameters pMenu 

Pointer to the menu to which a command is to be added. 
15 szCmdStringr 

The command string that is to be added to pMenu. 
dwCmdJD 

The command ID that is to be added to the voice menu. 
See Remarks. 
20 dwFlags 

Usually set to 0 to allow the system to handle the 
.Redback. If the application wunis to coi:n7?;:fi'/K^ck: : ii; 

: - /- : can pass:- . '!' 

_none Application handles the feedback ;or.e. 

25 . . _tone Feedback is always .'ons. . 

_echo Feedback is always echo. 



30 Remarks 



35 



Must be NULL. 

To avoid string ID duplication, if your application uses speech- 
enabled controls, make sure you use the following ranges to 
assign IDs in resource file: 

• Application 0 to 0x7FFF 

• Speech enabled controls 0x8000 to OxFFFF. 



40 



45 



IAPCSpeech::AttribGet 

IAPCSpeech::AttribGet gets speech-related settings. 

Syntax STDMETHOD lAPCSpeech::AttribGet(THIS_D WORD 

dwAtirib, PDWORD pdwMisc) PURE; 

Remarks AttribGet 2nd AttribSet are now called by the shell and the 

control panel applications. Your application should not call them 
at the present time. 
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lAPCSpeech::AttribSet 

IAPCSpeech::AttribSet sets or changes speech-related settings. 

5 Syntax STDMETHOD IAPCSpeech::AttribGet(THIS_DWORD 

dwAttrib, DWORD dwMisc) PURE; 

Remarks AttribGet and AttribSet are now called by the shell and the 

control panel applications. Your application should not call them 
10 at the present time. 

IAPCSpeecb::CreateVMenu 

IAPCSpeech::CreateVMenu creates a voice menu. 

STDMETHODIAPCSpeech::CreateVMenu 
(THISJ>1V0ICECMDW pVCmd, 
LPCTSTR IpMenuName 
HINSTANCE hlnst 
DWORD dwCmdCnt 

., lPy<)mpCndTab!e-> ■ : 

DWORD dwFifigi-' ■ 
PIVCMDMENUW* pp VMenu) PURE; 

pVCmd 

Pointer to a voice command. Usually an application 
should pass null, unless it creates the voice command. 
IpMenuName 

Unique menu name for each Apcspch object. 

hlnst 

Application or dynamic link library instance handle. 
dwCmdCnt 

Table size. 
pCmdTable 

Points to a GrammarlD table which stores the resource 
string ID. 
dwFIags 

Must be set to 0 or flag listed below. (See Remarks.) 
pp VMenu 

Pointer to a voice menu pointer. 

Remarks 1. dwFIags 

APCSPCH_VM_USEEXISTJNG 

The APCSPCH_VM JJSEEXISTING Hag can be passed 
in the dwFIags parameter. When 
APCSPCH_VMJJSEEX1STING is set and the 
application finds that the menu already exists, it will use 
the menu stored in the storage fite. You can still pass in 



20 



25 

Parameters 



30 



35 



40 
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the string table pointer and it is ignored if the 
APCSPCH_VMJJSEEXJ STING flag is set and there are 
commands in the menu. 

NOTE: APCSPCH_VM_USEEX1STING applies only to 
5 the Create VMenu function. A developer should be careful 

about using AddVMenuCommand while using the 
APCSPCH_VM_USEEXJSTING flag and CreateVMe'nu 
to create a voice menu. AddVMenuCommand does not 
check to determine whether the command is already stored 
1 0 or not. Make sure that you do not add the same command 

twice. 

2. The caller is responsible for releasing the menu object by 

calling Release. To create a menu in the default voice 
command pVCmd should be NULL. If the application has 
1 5 another voice command, it can pass it to p VCmd. 

3. The application should call the Activate and Deactivate 

functions of the menu object to activate or deactivate the 
grammar. 

20 

JAPCSpeecb::QuerylDterface 

I:^CSpeech::Queryinierface returns a pokier to an lAFCSpeech 
interface. 

STDMETHOD lAPCSpeech::Quer>'lnterface(THIS_REFIID riid. 
LPVOID FAR* ppvObj) PURE; 

riid 

[in] Specifies the IID of the interface being requested. 

ppvObj 

[out] Receives a pointer to an interface pointer to the 
object on return. If the interface specified in iid is not 
supported by the object, ppvObject is set to NULL. 

The application can call Query Interface to obtain the 
HDJVoiceCmd, HDJVoiceText, and other related VoiceCmd 
and VojceText interface pointers. 

40 

lAPCSpeech::Release 

The lAPCSpeech::Release method decrements the reference 
count for the calling interface on a speech object. 

45 

STDMETHOD JULONG) lAPCSpeech::Release(THIS) PURE; 



Parameters 

30 



35 

Remarks 
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IAPCSpeech::Speak 

lAPCSpeech::Speak says or speaks the string stored in szTTS 
using TTS. 

5 

STDMETHOD lAPCSpeech::Speak(TH!S_WCHAR* szTTS\ 
DWORD dwJD) PURE; J 

Parameters szTTS 
1 0 String that is to be said or spoken. 

wID 

String buffer ID. 



15 



Remarks If the parameter is null, it stops the speech output. 



lAPCSpeecb::Train 



IAPCSpeech::Train trains the application to recognize a user 
20 command. It deals with only one command at a time. The 

function pops up a training form to help the user train the 

- " application to recogniz? a word or command. Th* fvnc;;:vi is " 

- - /'blocked until the .training is fimshed-br cancelled. 

. STDMETHOD JAPCSpeech::7rain(THIS BSTR teirrha^ t 

PVOID pFormManager) PURE; 

Parameters bsirPhrase 

The word being trained. 
30 pFormMa nager 

Pointer to the application form manager. 



35 



lAPCSpeecb::VoiceHelpStart 



IAPCSpeech::VoiceHelpStart is called by the shell to start voice 
help. 



STDMETHOD IAPCSpeech::VoiceHelpStart(THIS_DWORD 
40 promptType)P\JKE\ 

Parameters prompiType 

Reserved. Must be 0. 

45 Remarks The application should not call VoiceHelpStart or 
VoiceHelpStop. 
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IAPCSpeech::VoiceHelpStop 

IAPCSpeech::VoiceHelpStop is called by the shell to stop voice 
help. 

5 

STDMETHOD IAPCSpeech::VoiceHelpStop(THISJDWORD 
dwReserved)?\JRE; 

Parameters dwReserved 
10 Reserved. Must be 0. 

Remarks Your application must not call VoiceHelpStart or VoiceHelpStop. 

15 CreateAPCSpeechObject 

CreateAPCSpeechObject creates an Auto PC speech object. 

Syntax CAPCSpeech* CreateAPCSpeechObject(LPCTSTR IpName, 

20 DWORD dwNotifylD, 

DWORD dwFlags, 

• • DWORD dw VCm dOptkw: -: ^-^-v ;/;\\: i>\jf-:.&V -Y : r " 

DWORD dwTxiOvtion): 

25 Parameters Note: At (his writing you may use either the ttiread riielhctfor 

sink method to create a speech object, however, in the future only 
the sink method may be supported. If your application uses a 
control that has the speech enabled such as an edit control or an 
HTML control, you must create the application using the sink 

30 method. 

IpName 

A unique name, usually the application name. 
dwNotifylD 

Thread Method: The thread ID where the notification 
35 messages are posted. Sink Method: The form manager 

pointer. 
dwFlags 

Thread Method: Must be 0. Sink Method: Should be 
APCSPCH_CBFORMSINK. 

40 dwVCmdOpiion 

This should be set to 0 if the caller is only interested in the 
recognition notification WM_SPCH_RECOG. It can also 
be combinations of the following flags: 
VCMDRF_CMDOTHER, V CM DRF_CMD START, 

45 VCMDRFATTR1B CHANGE. 

dwTxtOption 

This can be a combination of the followine flags: 
VTXTF_SPEAK, VTXTF_SPEAKDONE~ 
VTXTF_SPEAKSTOP, VTXTF_SPEAKSTART. 
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To avoid string ID duplication, if your application uses 
speech-enabled controls, make sure you use the following 
ranges to assign string IDs in resource file: 

• Application 0 to 0x7FFF. 

• Speech-enabled controls 0x8000 to OxFFFF. I 
An application can embed ''Xmrk^xV strings inside the 
text to be spoken. When the speech engine encounters the 
bookmarks, a WM_SPCH_NOTIFY 
(wParam=VTXTF_SPEAK, lParam=bookmarkID) 
message will be posted to the application. The traditional 
Spezk(stringJD) will also work because the system adds 
\mrk=ID\ before the string and then sends it to the engine. 
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Detailed Description of an Out-of-Memory API 
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Chapter 29 

Out of Memory User Interface Reference 

The out of memory component (Oomui) is a replaceable 
5 component that defines the behavior of the Windows CE 

operating system, including various dialogs and messages, when 
an out of memory situation is detected. j 

If you choose to replace the out of memory component with a 
10 customized out of memory component, you must implement all of 

the functions described in this section. Microsoft can provide 
assistance in this effort, in the form of sample code, upon request. 



15 OomUI_CreateNotRespondingWindow 



20 



The OomUI_CreateNotResponding Window function creates and 
returns a handle to a message dialog indicating that an application 
is not responding. 



Syntax HWND OomUI_CreateNotRespondingWindow(void) 

Parameters None. 
25 Return Value Handle to the created window. 



Remarks The OomUMTreateNotResponding Window function creates and 
returns a handle to an Application Not Responding dialog. This 
dialog is displayed if the out of memory component is unable to 
30 close a running application. The Out of Memory component 

should not destroy or hide this window. This function is declared 
in the header file oomui.h. 



35 OomUI_CreateOomWindow 

The OomUI_CreateOom Window function creates the Out of 
Memory dialog. 

40 Syntax HWND OomUI_CreateOomWindow(void); 

Parameters None. 

Return Value Returns a handle to the created window. 

45 

Remarks Creates and returns a handle to the Out of Memory dialog. The 
Out of Memory dialog is immortal, meaning that it should not be 
destroyed or hidden by the Out of Memory component. This 
function is declared in the header file oomui.h. 
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OomUl_FSbo\vOomWindow 

The OomUI_FShowOom Window function is called when the 
system determines that the Out of Memory window should be 
shown. It does not display the dialog, however. 

Syntax BOOL OomUI_FShowOomWindow(void) 

Parameters None. 

Return Value Returns TRUE if the Out of Memory window should be shown; 
otherwise, FALSE. 



Remarks This function gives the Out of Memory component a chance to 
prevent the Out of Memory dialog from appearing (by returning 
FALSE). This is not recommended, however, unless there are no 
options available to the user to free more memory. This function 
20 is declared in the header file oomui.h. 



OomUI_lnitialize 

25 The OomUMnitialize fraction is called civet to initialize the Out 

of Memory user interface component. 

Syntax VOID OomUI Jnitialize( 

H INSTANCE hinst 

30 ); 

Parameters hinst 

The HINSTANCE to use for loading resources. 

35 Return Value None. 

Remarks This function is called only once. It gives the Out of Memory 
user interface component an opportunity to do whatever 
initialization is needed. This function also informs the Out of 
40 Memory component of the current HINSTANCE, which is used 

to load resources. This function is declared in the header file 
oomui.h. 



45 OomUIJVotRespondingWndProc 

The window procedure for the Not Responding dialog. 



SUBSTITUTE SHEET (RULE 26) 



WO 99/49394 



PCT/US99/06223 



10 



15 



225 

Syntax L RESULT CALLBACK OomUI_OomWndProc( 

HWNDMwk/, 
UINT message, 
WPARAM wParam, 
LP ARAM IParam 

); 

Parameters hwnd 

Handle to the Application Not Responding dialog. 
message 

A windows message (e.g., WM_CLOSE). 
wParam 

Message-specific parameter. 

IParam 

Message-specific parameter. 

Remarks This function is the window procedure for the Application Not 
Responding window. This function is declared in the header file 
oomui.h. 



20 



OomUI OnShow 



30 



The OomUJJDnShow function is called just prior to the showing 
oftheOutqfM 

Syntax VOID OomUl_OnShow(void)) 

Parameters None. 

Return Value None. 



Remarks The OomUIJDnShow function is called just before the Out of 
Memory dialog is shown. The OomUI_OnShow function is not 
required to do anything, but may be used to, for example, set the 
title of the Out of Memory dialog or collect system information to 
be displayed in the Out of Memory dialog. This function is 
declared in the header file oomui.h. 



40 

OomUI_OomWndProc 



The window procedure for the Out of Memory dialog. 

45 Syntax L RESULT CALLBACK OomUI_OomWndProc( 

HWND hwnd, 
UINT message, 
WPARAM wParam, 
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LP ARAM IParam 

); 



Parameters 



35 



Remarks 



hwnd 

Handle to the Out of Memory window. 
message 

A message (e.g., WM_CLOSE). 
wParam 

Message-specific parameter. 

IParam 

Message-specific parameter. 

This function is the window procedure for the Out of Memory 
window. This function is declared in the header file Oomui.h. 



OomUI_SetWindowsJnfo 



The OomU3_SetWindowsInfo function provides the Out of 
Memory component with information regarding the windows to 
be closed. 



Svntax 



Parameters 



VOID Oc:nUI_SetWindowsInfo( 
INT c Windows; 
.WINDOWINFO^ rgwi 

); 

c Windows 

Number of entries in the rgwi array. 

rgwi 

Array of WINDOWINFO structures. 



Return Value None 
Remarks 



The OomUl_SetWindowslnfo function specifies to the Out of 
Memory component the windows to be closed. Each window is 
represented as a WINDOWINFO structure. This function and the 
WINDOWINFO structure are declared in the header file oomui.h. 



40 See Also WINDOWINFO 



OomUlCallBack CloseWindow 



45 



The OomUICal]back_Close Window function attempts to close a 
window. 
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Syntax BOOL OomU3Callback_C]oseWindow( 

WINDOWINFO* pwi 

); 

5 Parameters pwi 

Pointer to a WINDOWINFO structure. 
Return Value Returns TRUE if WM_CLOSE was sent; otherwise FALSE. 

1 0 Remarks The OomUlCallbackJTloseWindow function is called by the Out 
of Memory component, and indicates that the Out of Memory 
component is attempting to close a window (via WM_CLOSE). 
If this function returns FALSE, the window could not be sent a 
WM_CLOSE. If the function returns TRUE, it was sent a 

1 5 WM_CLOSE message. Note that a TRUE return value does not 

indicate whether the specified window was actually closed: 

For more information, see Sample Serial Port Driver. 

OomUICallbaekJsCritical 

• : The OomUICallbaekJsCritical function ii ceiled by >i^Gui of" 
Memory component to determine if memc-y is critically lew. 

Syntax BOOL OomUICallbackJsCritical(void) 

Parameters None. 

30 Return Value None. 

Remarks The OomUICallbaekJsCritical function is called by the Out of 
-Memory component to determine if memory is critically low. 
This function is declared in the header file Oomui.h. 



20 



25 



35 



OomUlCallbackJVonClientPaint 



The OomUlCallbackJVonClientPaint function is called by the 
40 Out of Memory component to paint its non-client area in the 

"active" colors. 

Syntax VOID OomUlCallback_NonClientPaint( 

HWND hwnd 

45 ); 

Parameters hwnd 

Handle to the window. 
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Return Value None. 



Remarks The OomUlCal]back_NonClientPaint function causes the non- 
client area (the title bar) to be painted in its "active" color. This 
function is declared in the header file Oomui.h. 



WINDOW1NFO 



10 The WTNDOWINFO structure defines the window handle, 

window name, and close options for a window. 

Syntax typedef struct { 

HWND hwnd; 
1 5 LPCTSTR sz WindowName; 

UINT32 JToBeClosed; 
UINT32 JToBeTerminated; 
} WINDOWINFO; 

20 Members hwnd 

Handle to the window. 
szWindowName 

x ■:• ' Tiiie of the wmvio^;.- - - : - : - 

. JToBeClosed 

25 A value of 1 indicates that the window slio«tt m ck^ed. 

JToBeTerminated 

A value of 1 indicates that the window should be 
terminated. 



30 Remarks 



The WINDOWINFO structure supports the implementation of the 
Out of Memory component. This structure is declared in header 
file Oomui.h. 



See Also OomUI_SetWindowsInfo, OomUl_SetWindowsInfo, 
35 OomUICallback CloseWindow. 
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Conclusion 

APIs for modules and components of a resource-limited operating system 
have been described. The. APIs provide access to specialized hardware and 
software that is desirable in such limited-resource systems. 
5 Although specific embodiments have been illustrated and described 

herein, it will be appreciated by those of ordinary skill in the an that any 
arrangement which is calculated to achieve the same purpose may be substituted 
for the specific embodiments shown. This application is intended to cover any 
adaptations or variations of the present invention. 
1 0 For example, those of ordinary skill within the an will appreciate that 

while the embodiments of the invention have been described as being 
implemented in a resource-limited environment, the principles of the invention 
are applicable to other environments. For example, the voice command APIs 
can be adapted to standard desk-top operating system to aid user's who have 
] 5 difficulty using a convert ion^r;< eyboard %?\i^n?mz vo provide jnpatr".c a system. 

The terminology used in this application is meant to include fill of these 
environments. Therefore, it is manifestly intended that this invention be limited 
only by the following claims and equivalents thereof. 



SUBSTITUTE SHEET (RULE 26) 



WO 99/49394 



230 



PCT/US99/06223 



What is claimed is: 

1 . A computer system comprising: 

a computer comprising a processor and a memory operatively coupled 
5 together; 

an operating system executing in the processor, said operating system having a 
handwriting recognition component; 

an application program running under the control of the operating 
system; and 

1 0 application program interfaces associated with the handwriting 

recognition component, said application program interfaces operative to receive 
data from the application and send data to the application. 

2. The computer system of claim 1, wherein the application program 
•15.; . -interfaces comprises, .? . ■ * * - " ■ -\ . - . 

a first interface that receives a source handwriting context handle from un 
application arid returns to the application a target handwriting context handle that 
is based on the source handwriting context handle; 

a second interface that receives a first handwriting context handle from 
20 an application that causes the handwriting recognition component to destroy the 
first handwriting context handle; 

a third interface that receives from an application an input handwriting 
context handle and an array of points representing a mouse stroke, and that 
causes the handwriting recognition component to add the array of points to a 
25 data structure represented by the input handwriting context handle; 

a fourth interface that receives from an application the input handwriting 
context handle from an application and that causes the handwriting recognition 
component to stop adding arrays of points to the data structure represented by 
the input handwriting context handle; 
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a fifth interface that receives from an application the input handwriting 
context handle and that causes the handwriting component to interpret the data 
structure represented by the input handwriting context handle; 

a sixth interface that receives the input handwriting context handle pom 
5 the application and that returns to the application at least one character that is 
based on the array of points in the handwriting recognition context; and 

a seventh interface that receives the input handwriting context handle and 
a context character from an application and that causes the handwriting 
recognition component to interpret the arrays of points based on the context 
1 0 character. 

3. A set of application program interfaces embodied on a computer-readable 
medium for execution on a computer in conjunction with an application that 
interfaces with a handwriting recognition component, comprising: 
i.5 a first interface 'hat rece^ r'^.-v^p^"- 
application and returns to the application a target handwriting context handle th&t 
is based on the source handwriting context handle; 

a second interface that receives a first handwriting context handle from 
an application that causes the handwriting recognition component to destroy the 
20 first handwriting context handle; 

a third interface that receives from an application an input handwriting 
context handle and an array of points representing a mouse stroke, and that 
causes the handwriting recognition component to add the array of points to a 
data structure represented by the input handwriting context handle; 
25 a fourth interface that receives from an application the input handwriting 

context handle from an application and that causes the handwriting recognition 
component to stop adding arrays of points to the data structure represented by 
the input handwriting context handle; 

a fifth interface that receives from an application the input handwriting 
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context handle and that causes the handwriting component to interpret the data 
structure represented by the input handwriting context handle; 

a sixth interface that receives the input handwriting context handle from 
the application and that returns to the application at least one character that is 
5 based on the array of points in the handwriting recognition context; and 

a seventh interface that receives the input handwriting context handle and 
a context character from an application and that causes the handwriting 
recognition component to interpret the arrays of points based on the context 
character. 

10 

4. A computer system comprising: 

a computer comprising a processor and a memory operatively coupled 
together; 

an operating system executing in the processor, said operating system 
15 r having- a positioning. €omponch^- 8 "-" ; -VK iL ' '• " : " : " 

an application program running "under the control of the operating 
system; and 

application program interfaces associated with the positioning 
component, said application program interfaces being functional to allow the 
20 application program to cause the positioning component to send and receive data 
from a positioning device. 

5. The computer system of claim 4, wherein the positioning device 
comprises a Global Positioning System (GPS). 

25 

6. The computer system of claim 5 ? wherein the GPS comprises an Apollo 
GPS. 
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7. The computer system of claim 4, wherein the application program 
interfaces comprise: 

a first interface that receives a first device handle from an application, 
said first device handle referring to the positioning device, and that returns to the 
5 application a status value indicating whether or not the positioning device was 
successfully closed; 

a second interface that returns a list of positioning devices to the 
application; and 

a third interface that receives a positioning device profile from an 
1 0 application and that returns to the application a second device handle 

representing the positioning device, said positioning device being placed in an 
open state. 

8. The computer system of claim 4, wherein the application program 
15 . .inierfacesxQm^ise: \.\ .. .... . y ■ 

a fourth interface ih.at receives a first handle to the positioning device and 
a first data type from an application and that returns a data value to the 
application based on the first data type; and 

a fifth interface that receives a second handle to the positioning device, a 
20 data buffer containing data to be sent to the positioning device, and a second data 
type from the application and that returns to the application a status indicating 
whether or not the data buffer was successfully sent to the positioning device. 

9. The computer system of claim 8, wherein the first data type is selected 
25 from the group consisting of: position, velocity, device state, time, accuracy 
station, device profile, configuration, settings, differential GPS status, and 
almanac. 
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10. The computer system of claim 8, wherein the second data type is selected 
from the group consisting of: position, velocity, device state, time, accuracy . 
station, device profile, configuration, settings, differential GPS status, and 
almanac. 

5 

1 1 . The computer system of claim 4, wherein the application program 
interfaces comprise: 

a sixth interface that receives a device handle to the positioning device, a 
data type and a time period from the application, and that causes the positioning 
1 0 component to retrieve data from the positioning device once each time period, 
said retrieved data based on the data type; and 

a seventh interface that receives a second device handle to the positioning 
device and a data type from an application, and that causes the positioning 
component to stop retrieving data of the type specified by the data type. 

12. The computer systcm of claim 4, wherein the application program ' : 
interfaces further comprise an eighth interface the returns to an application the 
quality of service provided by the positioning device. 

20 13. A set of application program interfaces embodied on a computer-readable 
medium for execution on a computer in conjunction with an application that 
maintains positioning data, comprising: 

a first interface that receives a first device handle from an application, 
said first device handle referring to the positioning device, and that returns to the 
25 application a status value indicating whether or not the positioning device was 
successfully closed; 

a second interface that returns a list of positioning devices to the 
application; and 
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a third interface that receives a positioning device profile from an 
application and that returns to the application a second device handle 
representing the positioning device, said positioning device being placed in an 
open state. 

5 

14. The set of application program interfaces of claim 13, wherein the 
application program interfaces further comprise: 

a fourth interface that receives a first handle to the positioning device and 
a first data type from an application and that returns a data value to the 
3 0 application based on the first data type; and 

a fifth interface that receives a second handle to the positioning device, a 
data buffer containing data to be sent to the positioning device, and a second data 
type from the application and that returns to the application a status indicating 
whether or not the data buffer was successfully sent to the positioning device. 
15 . " ,- • - -- ■ 

15. The set of application program interfaces of claim 14, wherdri the first 
data type is selected from the group consisting of: position, velocity, device 
state, time, accuracy station, device profile, configuration, settings, differential 
GPS status, and almanac. 

20 

1 6. The set of application program interfaces of claim 1 4, wherein the second 
data type is selected from the group consisting of: position, velocity, device 
state, time, accuracy station, device profile, configuration, settings, differential 
GPS status, and almanac. 

!5 

17. The set of application program interfaces of claim 13, wherein the 
application program interfaces further comprise: 

a sixth interface that receives a device handle to the positioning device, a 
data type and a time period from the application, and that causes the positioning 
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component to retrieve data from the positioning device once each time period, 
said retrieved data based on the data type; and 

a seventh interface that receives a second device handle to the positioning 
device and a data type from an application, and that causes the positioning 
component to stop retrieving data of the type specified by the data type. 

1 8. The set of application program interfaces of claim 13, wherein the 
application program interfaces further comprise an eighth interface the returns to 
an application the quality of service provided by the positioning device. 



1 9. A computer readable medium having stored thereon a data structure 
comprising: 

a first field comprising a data item indicating a position and a data item 
indicating a time that the data item indicating a position was set; 
1 5 a second field comprising aJmanar. Aim received from a jx^tienmg 

device operably coupled to an embedded .. system; 

a third field comprising an indicator indicating whether the second field 
is initialized upon startup of the embedded system; 

a fourth field comprising an indicator indicating whether the data item 
20 indicating a position is initialized upon startup of the embedded system; and 
a fifth field comprising an indicator indicating whether the data item 
indicating a time is initialized upon startup of the embedded system. 

20. A computer readable medium having stored thereon a data structure 
25 comprising: 

a first field comprising a manufacturer name for a positioning device; 
a second field comprising a name for the chip manufacturer and chip 
model of the positioning device; 
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a third field comprising a number of applications using the positioning 

device; 

a fourth field comprising the quality of data provided by the positioning 

device; 

5 a fifth field comprising a pointer to a data structure describing the next 

positioning device; and 

a sixth field identifying a communications port used by the positioning 

device. 

10 21. A computer readable medium having stored thereon a data structure 
comprising: 

a first field comprising the state of a positioning device; and 
a second field comprising a time indicating when the. first field was 
updated. 

22. A computer readable medium having stored thereon a data structure 
comprising: 

a first field comprising a positioning device mode for a positioning 

device; 

20 a second .field comprising an operational mode for the positioning device; 

a third field comprising a correction status for the positioning device; 
a fourth field comprising a time indicating when the first field, second 
field and third field were set; and 

a fifth field comprising a maximum age limit assigned to the positioning 

25 device. 

23. A computer readable medium having stored thereon a data structure 
comprising: 

a first field comprising a station number identifying a station; 
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a second field indicating whether the station identified by the first field is 
used during a predetermined data processing step that calculates a position; 
a third field comprising an elevation of the station; 
a fourth field comprising an azimuth value for the station; and 
5 a fifth field comprising the strength of the signal received from the 

station. 

24. A computer readable medium having stored thereon a data structure 
comprising: 

1 0 a fi rst fie,d comprising a position for a positioning device coupled to an 

embedded system; and 

a second field comprising a time when the position of the first field was 
acquired. 

15 25. A set of application program imeriaoes embodied on a ro"nputev-:^o^k " " 

medium for execution on a computer in conjunction with an application ihat 

provides text output, comprising: 

a first interface that receives an application identifier, a notification 

interface, an identifier for the notification interface, a flag identifying. a set of 
20 notifications to be sent to the notification interface, and a reference to a site 

information structure and that registers the application with a text-to-speech 

component; and 

a second interface that receives a buffer containing text, a priority flag 
indicating the type of text, and a buffer that contains text-to-speech control tags 
25 and that causes the text-to-speech component to convert the buffer containing 
text to audio output. 

26. The set of application program interfaces of claim 25, fiirther comprising: 
a third interface that causes the text-to-speech component to stop playing 
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the buffer containing text and to flush a set of pending text from a playback 
queue; 

a fourth interface that causes the text-to-speech component to pause 
playing the buffer containing text; and 
5 a fifth interface that causes the text-to-speech component to resume 

playing the buffer containing text. 

27. The set of application program interfaces of claim 25, further comprising: 
a sixth interface that returns a flag indicating the current speech status; 

1° a seventh interface that receives a first talking speed that causes the text- 

to-speech component to output text at the first talking speed; 
an eighth interface that returns a current talking speed; 
a ninth interface that receives a first voice identifier that indicates a voice 
to be used by the text-to-speech component; and 
;15; . » - a. tenth interface that^returns a sec?m£-- voitib -?<X^k IZ&'zMx in^ica?>s*ffi/v : ■> - 
current voice used by the text-to-speech component. . . ■ . - 

28. A set of application program interfaces embodied on a computer-readable 
medium for execution on a computer in conjunction with an application that 

20 manages at least one voice command menu, comprising: 

a first interface that receives a handle of a window associated with the at 
least one voice command menu and a flag indicating when the menu should be 
active in relation to a speech recognition status; 

a second interface that receives a list of command structures, each of said 
25 command structures describing a voice command, and that returns a number 
associated with a first voice command added to the at least one voice command 
menu; 

a third interface that deactivates the at least one voice command menu; 

and 
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a fourth interface that receives a number corresponding to a first voice 
command, a number of voice commands to remove and that removes the number 
of voice commands from the at least one voice command menu, said removal 
starting with the number corresponding to the first voice command. 

5 

29. A set of application program interfaces embodied on a computer-readable 
medium/or execution on a computer in conjunction with an application that 
manages a voice command menu, comprising: 

a first interface that receives an enablement parameter from an 
1 0 application, said enablement parameter operative to cause a voice recognition 
component to enable voice recognition when the enablement parameter has a 
first value and to disable voice recognition when the enablement parameter has a 
second value; and 

a second interface that returns a second parameter to the application, said 
> 15 second : ^arameter ophr£i^ 

second parameter has the first value and that voice recognition is disabled when 
the second parameter has the second value. 

30. A set of application program interfaces embodied on a computer-readable 
20 medium for execution on a computer in conjunction with an application that 

manages a voice command menu, comprising: 

a first interface that receives a first voice command structure identifying a 
voice menu and a command string, said voice command structure having an 
association with a second application; 
25 a second interface that receives an identifier of a recognized voice 

command, a second voice command structure identifying a voice menu 
associated with the recognized voice command, a verification required flag, an 
action data string, a list containing at least one recognized phrase of the 
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recognized voice command, and a command string corresponding the recognized 
command; 

a third interface that is called when a spoken phrase is detected by a voice 
command component; and 
5 a fourth interface that receives a type of interference detected by the 

voice command component. 

31 . A set of application program interfaces embodied on a computer-readable 
medium for execution on a computer in conjunction with an application that 

1 0 manages a voice command menu, comprising: 

a first interface that receives a menu identifier structure, said menu 
identifier structure comprising an application name and a state name, a language 
identifier structure and a mode flag from an application that causes a voice 
recognition system to create a voice command menu identified by the menu 

IS*. v - -idemifierMmclufe; in'd "V5-A : - v^vU - 

, a second interface that receives the menu identifier structure from an . 
application and that causes the voice recognition system to delete the voice 
command menu identified by the menu identifier structure. 

20 32. A computer system comprising: 

a computer comprising a processor and a memory operatively coupled 
together; 

an operating system executing in the processor, said operating system having a 
speech-to-text component; 
25 an application program running under the control of the operating 

system; 

application program interfaces associated with the speech-to-text 
component, said application program interfaces operative to receive data from 
the application and send data to the application. 
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33. The computer system of claim 32, wherein the application program 
interfaces comprise: 

a first interface that receives an application identifier, a notification 
5 interface, an identifier for the notification interface, a flag identifying a set of 
notifications to be sent to the notification interface, and a reference to a site 
information structure and that registers the application with a text-to-speech 
component; and 

a second interface that receives a buffer containing text, a priority flag 
1 0 indicating the type of text, and a buffer that contains text-to-speech control tags 
and that causes the text-to-speech component to convert the buffer containing 
text to audio output. 

34. The computer system of claim 32, wherein the application program 
15 interfaces comprise: . _ . ^ : - ■ 

a third interface that causes the text-to- speech component to stop playing 
the buffer containing text and to flush a set of pending text from a playback 
queue; 

a fourth interface that causes the text-to-speech component to pause 
20 playing the buffer containing text; and 

a fifth interface that causes the text-to-speech component to resume 
playing the buffer containing text. 

35. The computer system of claim 32, wherein the application program 
25 interfaces comprise: 

a sixth interface that returns a flag indicating the current speech status; 
a seventh interface that receives a first talking speed that causes the text- 
to-speech component to output text at the first talking speed; 
an eighth interface that returns a current talking speed; 
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a ninth interface that receives a first voice identifier that indicates a voice 
to be used by the text-to-speech component; and 

a tenth interface that returns a second voice identifier that indicates the 
current voice used by the text-to-speech component. 

5 

36. A computer system comprising: 

a computer comprising a processor and a memory operatively coupled 
together; 

an operating system executing in the processor, said operating system having a 
1 0 voice recognition component; and 

an application program running under the control of the operating 

system; 

application program interfaces associated with the voice recognition component, 
said application program interfaces operative to receive data from the application 
15 and send data to the application, : : v : - - :i 

37. The computer system of claim 36, wherein the application program 
interfaces comprise: 

a first interface that receives a handle of a window associated with the at 
20 least one voice command menu and a flag indicating when the menu should be 
active in relation to a speech recognition status; 

a second interface that receives a list of command structures, each of said 
command structures describing a voice command, and that returns a number 
associated with a first voice command added to the at least one voice command 
25 menu; 

a third interface that deactivates the at least one voice command menu; 

and 

a fourth interface that receives a number corresponding to a first voice 
command, a number of voice commands to remove and that removes the number 
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of voice commands from the at least one voice command menu, said removal 
starting with the number corresponding to the first voice command. 

38. The computer system of claim 36, wherein the application program 
5 interfaces comprise: 

a first interface that receives an enablement parameter from the 
application, said enablement parameter operative to cause the voice recognition 
component to enable voice recognition when the enablement parameter has a 
first value and to disable voice recognition when the enablement parameter has a 
10 second value; and 

a second interface that returns a second parameter to the application, said 
second parameter operative to indicate that voice recognition is enabled when the 
second parameter has the first value and that voice recognition is disabled when 
the second parameter has the second value. 

39. The computer system of claim 36, wherein the application program 

interfaces comprise: 

a first interface that receives from the application a first voice command 

structure identifying a voice menu and a command string, said voice command 
20 structure having an association with a second application; 

a second interface that receives an identifier of a recognized voice 

command, a second voice command structure identifying a voice menu 

associated with the recognized voice command, a verification required flag, an 

action data string, a list containing at least one recognized phrase of the 
25 recognized voice command, and a command string corresponding the recognized 

command; 

a third interface that is called when a spoken phrase is detected by the 
voice recognition component; and 
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a fourth interface that receives a type of interference detected by the 
voice recognition component. 

40. The computer system of claim 36, wherein the application program 
5 interfaces comprise: 

a first interface that receives a menu identifier structure, said menu 
identifier structure comprising an application name and a state name, a language 
identifier structure and a mode flag from an application that causes a voice 
recognition system to create a voice command menu identified by the menu 
1 0 identifier structure; and 

a second interface that receives the menu identifier structure from an 
application and that causes the voice recognition system to delete the voice 
command menu identified by the menu identifier structure. 

1 ? 41. A computer readable medium having stored thereon a data structure 
comprising: 

a first field comprising a command string for a voice command; 
a second field comprising a flag having values providing information 
about the voice command; 
20 a third field comprising a command identifier for the voice command; 

a fourth field comprising a description of an action performed in response 
to the voice command; and 

a fifth field comprising a category identifier for the voice command. 

25 42. A computer readable medium having stored thereon a data structure 
comprising: 

a first field comprising a recognition threshold for a voice recognition 
engine; 
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a second field comprising an identifier for an input audio device 
supplying input to the voice recognition engine; 
a third field comprising a flag indicating whether voice recognition is 
enabled; 

5 a fourth field comprising the name of a current microphone for the audio 

input device identified by the second field; 

a fifth field comprising the name of a current speaker that is the audio 
source; and 

a sixth field comprisng an identifier for a speech-recognition mode. 

10 

43. A computer readable medium having stored thereon a data structure 
comprising: 

a first field comprising an identifier for an input audio device supplying 
input to a voice recognition engine; 

\rS\ : • a* second, f :£].<}.< comprising * a flag indicating '-whether vaic-r. 'i^ccgvfcittiz^' ' 
enabled; and 

a third field comprising a baseline average talking speed for the voice 
recognition engine. 

20 44. A computer system comprising: 

a computer comprising a processor and a memory operatively coupled 
together; 

an operating system executing in the processor, said operating system having an 
out of memory module; 
25 application program interfaces associated with the out of memory 

module, said application program interfaces being functional to allow the 
operating system to cause the out of memory module to respond to a low 
memory condition. 
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45. The computer system of claim 44, wherein the application program 
interfaces comprise: 

a first interface that receives from the operating system a list of window ■ 
structures that identify windows to be closed by the out of memory modulei and 
5 a second interface called by the out of memory module that causes the 

operating system to determine if memory is critically low. 

46. A set of application program interfaces embodied on a computer-readable 
medium for execution on a computer in conjunction with an out of memory 

1 0 module of an operating system, comprising: 

a first interface that receives from the operating system a list of window 
structures that identify windows to be closed by the out of memory module; and 

a second interface called by the out of memory module that causes the 
operating system to determine if memory is critically low. 



47. A computer readable medium having storied thereon a data structure 
comprising: 

a first field comprising a handle representing a folder containing a local 
20 object and a remote object; 

a second field comprising a handle representing the local object; 

a third field comprising a handle the remote object; 

a fourth field comprising a name of the local object; 

a fifth field comprising a description of the local object; 
25 a sixth field comprising a name of the remote object; and 

a seventh field comprising a description of the remote object; and 
wherein during a predetermined data processing operation the fourth, fifth, sixth 
and seventh fields are displayed. 
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48. A computer readable medium having stored thereon a data structure 
comprising: • 

a first field comprising an object type name; 

a second field comprising at least one indicator describing a file system 
5 object, said indicators including a changed indicator and a deleted indicator; 
a third field comprising an identifier for a file system object; 
a fourth field comprising a count of a number of file system object 
identifiers that are to be replicated if the changed indicator is set, otherwise 
comprising a count of a number of file system object identifiers in a list of 
1 0 changed objects if both the changed indicator and the deleted indicator are not 
set; and 

a fifth field comprising a count of a number of deleted object identifiers 
that are to be replicated if the deleted indicator is set, otherwise comprising a 
count of a number of file object identifiers in a list of unchanged objects if both 
15 the changed indicator ana the d&s*: indicator hi = Wi set. ■ '-"i-f, . 

49 A computer readable medium having stored thereon a data structure 
comprising: 

a first field comprising the name of an object type; 
20 a second field comprising a number of existing objects having the object 

type named in the first field; and 

a third field comprising a timestamp, said timestamp indicating a last 
time that an object having the object type named in the first field was modified. 

25 
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